From 1b2145d931d663c8b4362c310682407fe67eb3d4 Mon Sep 17 00:00:00 2001 From: Gerald Combs Date: Sun, 2 Feb 2014 11:00:30 -0800 Subject: [PATCH] Convert three more WSDG chapters: works, build, and capture. Start adding references to Qt and wsutil. Fix a file extension in CMakeLists.txt. Change-Id: I0cbe7e802d88a05effff40b5de72669e22c0df53 Reviewed-on: https://code.wireshark.org/review/79 Reviewed-by: Gerald Combs Tested-by: Gerald Combs --- docbook/CMakeLists.txt | 11 +- docbook/Makefile.common | 9 +- docbook/developer-guide.xml | 6 +- .../WSDG_chapter_build_intro.asciidoc | 54 ++++++ docbook/wsdg_src/WSDG_chapter_build_intro.xml | 69 ------- .../wsdg_src/WSDG_chapter_capture.asciidoc | 74 ++++++++ docbook/wsdg_src/WSDG_chapter_capture.xml | 82 --------- docbook/wsdg_src/WSDG_chapter_works.asciidoc | 115 ++++++++++++ docbook/wsdg_src/WSDG_chapter_works.xml | 168 ------------------ 9 files changed, 259 insertions(+), 329 deletions(-) create mode 100644 docbook/wsdg_src/WSDG_chapter_build_intro.asciidoc delete mode 100644 docbook/wsdg_src/WSDG_chapter_build_intro.xml create mode 100644 docbook/wsdg_src/WSDG_chapter_capture.asciidoc delete mode 100644 docbook/wsdg_src/WSDG_chapter_capture.xml create mode 100644 docbook/wsdg_src/WSDG_chapter_works.asciidoc delete mode 100644 docbook/wsdg_src/WSDG_chapter_works.xml diff --git a/docbook/CMakeLists.txt b/docbook/CMakeLists.txt index 56bec0f762..0e3f5456ef 100644 --- a/docbook/CMakeLists.txt +++ b/docbook/CMakeLists.txt @@ -182,8 +182,8 @@ set(WSUG_GRAPHICS ) set(WSDG_FILES - wsdg_src/WSDG_chapter_build_intro.xml - wsdg_src/WSDG_chapter_capture.xml + wsdg_generated_src/WSDG_chapter_build_intro.xml + wsdg_generated_src/WSDG_chapter_capture.xml wsdg_src/WSDG_chapter_dissection.xml wsdg_generated_src/WSDG_chapter_env_intro.xml wsdg_generated_src/WSDG_chapter_libraries.xml @@ -191,18 +191,21 @@ set(WSDG_FILES wsdg_generated_src/WSDG_chapter_sources.xml wsdg_generated_src/WSDG_chapter_tools.xml wsdg_src/WSDG_chapter_userinterface.xml - wsdg_src/WSDG_chapter_works.xml + wsdg_generated_src/WSDG_chapter_works.xml wsdg_src/WSDG_meta_info.xml wsdg_generated_src/WSDG_preface.xml ws.css ) set(WSDG_ASCIIDOC_FILES + wsdg_src/WSDG_chapter_build_intro.asciidoc + wsdg_src/WSDG_chapter_capture.asciidoc wsdg_src/WSDG_chapter_env_intro.asciidoc wsdg_src/WSDG_chapter_libraries.asciidoc - wsdg_src/WSDG_chapter_quick_setup.xml + wsdg_src/WSDG_chapter_quick_setup.asciidoc wsdg_src/WSDG_chapter_sources.asciidoc wsdg_src/WSDG_chapter_tools.asciidoc + wsdg_src/WSDG_chapter_works.asciidoc wsdg_src/WSDG_preface.asciidoc ) diff --git a/docbook/Makefile.common b/docbook/Makefile.common index 42c5042a52..5243672347 100644 --- a/docbook/Makefile.common +++ b/docbook/Makefile.common @@ -159,8 +159,8 @@ WSUG_GRAPHICS = \ wsug_graphics/toolbar/stock_zoom_out_24.png WSDG_FILES = \ - wsdg_src/WSDG_chapter_build_intro.xml \ - wsdg_src/WSDG_chapter_capture.xml \ + wsdg_src/WSDG_chapter_build_intro.asciidoc \ + wsdg_src/WSDG_chapter_capture.asciidoc \ wsdg_src/WSDG_chapter_dissection.xml \ wsdg_src/WSDG_chapter_env_intro.asciidoc \ wsdg_src/WSDG_chapter_libraries.asciidoc \ @@ -168,17 +168,20 @@ WSDG_FILES = \ wsdg_src/WSDG_chapter_sources.asciidoc \ wsdg_src/WSDG_chapter_tools.asciidoc \ wsdg_src/WSDG_chapter_userinterface.xml \ - wsdg_src/WSDG_chapter_works.xml \ + wsdg_src/WSDG_chapter_works.asciidoc \ wsdg_src/WSDG_meta_info.xml \ wsdg_src/WSDG_preface.asciidoc \ ws.css WSDG_GENERATED_SOURCE = \ + wsdg_src/WSDG_chapter_build_intro.xml \ + wsdg_src/WSDG_chapter_capture.xml \ wsdg_src/WSDG_chapter_env_intro.xml \ wsdg_src/WSDG_chapter_libraries.xml \ wsdg_src/WSDG_chapter_quick_setup.xml \ wsdg_src/WSDG_chapter_sources.xml \ wsdg_src/WSDG_chapter_tools.xml \ + wsdg_src/WSDG_chapter_works.xml \ wsdg_src/WSDG_preface.xml WSDG_GRAPHICS = \ diff --git a/docbook/developer-guide.xml b/docbook/developer-guide.xml index 2358839678..b1c6f9480b 100644 --- a/docbook/developer-guide.xml +++ b/docbook/developer-guide.xml @@ -109,12 +109,12 @@ FILE SECTION Wireshark Build Environment -Part I. Wireshark Build Environment +Part I. Wireshark Build Environment -The first part describes how to set up the tools, libraries and +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. +tasks. Part II. Wireshark Development diff --git a/docbook/wsdg_src/WSDG_chapter_build_intro.asciidoc b/docbook/wsdg_src/WSDG_chapter_build_intro.asciidoc new file mode 100644 index 0000000000..23e94af524 --- /dev/null +++ b/docbook/wsdg_src/WSDG_chapter_build_intro.asciidoc @@ -0,0 +1,54 @@ +++++++++++++++++++++++++++++++++++++++ + +++++++++++++++++++++++++++++++++++++++ + +[[ChapterBuildIntro]] + +== Introduction + +[[ChCodeOverview]] + +=== Source overview + +Wireshark consists of the following major parts: + +* Packet dissection - in the '/epan/dissector' and '/plugin/*' directories + +* File I/O - using Wireshark's own wiretap library + +* Capture - using the libpcap/winpcap library, in /wiretap + +* User interface - using the Qt or $$GTK+$$ and associated libraries + +* Utilities - miscellaneous helper code + +* Help - using an external web browser and GTK text output + +[[ChCodeStyle]] + +=== Coding Style + +The coding style guides for Wireshark can be found in the "Code style" +section of the file 'doc/README.developer'. + +[[ChCodeGLib]] + +=== The GLib library + +Glib is used as a basic platform abstraction library. It's doesn't provide +any direct GUI functionality. + +To quote the Glib Reverence Manual: +____ +GLib provides the core application building blocks for libraries and +applications written in C. It provides the core object system used in GNOME, the +main loop implementation, and a large set of utility functions for strings and +common data structures. +____ + +GLib contains lots of useful things for platform independent development. +See https://developer.gnome.org/glib/[] for details about GLib. + +++++++++++++++++++++++++++++++++++++++ + +++++++++++++++++++++++++++++++++++++++ \ No newline at end of file diff --git a/docbook/wsdg_src/WSDG_chapter_build_intro.xml b/docbook/wsdg_src/WSDG_chapter_build_intro.xml deleted file mode 100644 index 93106cf0b1..0000000000 --- a/docbook/wsdg_src/WSDG_chapter_build_intro.xml +++ /dev/null @@ -1,69 +0,0 @@ - - - - - Introduction - -
- Source overview - - Wireshark consists of the following major parts: - - - Packet dissection - in the /epan/dissector and /plugin/* directory - - - File I/O - using Wireshark's own wiretap library - - - Capture - using the libpcap/winpcap library, in /wiretap - - - User interface - using the GTK+ (and corresponding) libraries - - - 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 Concurrent Versions System - (CVS) to Subversion (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. - -
- -
- Coding styleguides - - The coding styleguides for Wireshark can be found in the "Code style" - section of the file doc/README.developer. - -
- -
- 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 - for details about GLib. - -
- - - diff --git a/docbook/wsdg_src/WSDG_chapter_capture.asciidoc b/docbook/wsdg_src/WSDG_chapter_capture.asciidoc new file mode 100644 index 0000000000..a6cd4dc930 --- /dev/null +++ b/docbook/wsdg_src/WSDG_chapter_capture.asciidoc @@ -0,0 +1,74 @@ +++++++++++++++++++++++++++++++++++++++ + +++++++++++++++++++++++++++++++++++++++ + +[[ChapterCapture]] + +== Packet capturing + +**** +This chapter needs to be reviewed and extended. +**** + +[[ChCaptureAddLibpcap]] + +=== How to add a new capture type to libpcap + +The following is an updated 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 protocols 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, in which case you might want separate ++$$DLT_*$$+ values. + +For the rest of the libpcap discussion, I'll assume you're working with libpcap +1.0 or later and that this is on a UN*X platform. You probably don't want to +work with a version older than 1.0, 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 +linktype+ +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 support, 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 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_add_uint()+. + +++++++++++++++++++++++++++++++++++++ + +++++++++++++++++++++++++++++++++++++ \ No newline at end of file diff --git a/docbook/wsdg_src/WSDG_chapter_capture.xml b/docbook/wsdg_src/WSDG_chapter_capture.xml deleted file mode 100644 index 6396c246dd..0000000000 --- a/docbook/wsdg_src/WSDG_chapter_capture.xml +++ /dev/null @@ -1,82 +0,0 @@ - - - - - Packet capturing - - - XXX - this chapter has to be reviewed and extended! - - -
- 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 protocols 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, 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 "linktype" 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 support, - 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 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_add_uint()". - -
- - - diff --git a/docbook/wsdg_src/WSDG_chapter_works.asciidoc b/docbook/wsdg_src/WSDG_chapter_works.asciidoc new file mode 100644 index 0000000000..725aad1b4f --- /dev/null +++ b/docbook/wsdg_src/WSDG_chapter_works.asciidoc @@ -0,0 +1,115 @@ +++++++++++++++++++++++++++++++++++++++ + +++++++++++++++++++++++++++++++++++++++ + +[[ChapterWorks]] + +== How Wireshark Works + +[[ChWorksIntro]] + +=== Introduction + +This chapter will give you a short overview of how Wireshark works. + +[[ChWorksOverview]] + +=== Overview + +The following will give you a simplified overview of Wireshark's function blocks: + +[[ChWorksFigOverview]] + +.Wireshark function blocks +image::wsdg_graphics/ws-function-blocks.png[] + +**** +This image is out of date. It is missing the utility library in 'wsutil' and +the Qt UI in 'ui/qt'. +**** + +The function blocks in more detail: +$$GTK+ 2$$:: Handling of all user input/output (all windows, dialogs and such). +Source code can be found in the 'ui/gtk' directory. + +Core:: Main "glue code" that holds the other blocks together. Source +code can be found in the root directory. + +Epan:: Ethereal Packet ANalyzer -- the packet analyzing engine. +Source code can be found in the 'epan' directory. Epan provides +the following APIs: + +* Protocol Tree. Dissection information for an individual packet. + +* Dissectors. The various protocol dissectors in +'epan/dissectors'. + +* Dissector Plugins - Support for implementing dissectors as separate modules. +Source code can be found in 'plugins'. + +* Display Filters - The display filter engine at +'epan/dfilter'. + +Wiretap:: The wiretap library is used to read andwrite capture files in libpcap, +pcapng, and many other file formats. Source code is in the +'wiretap' directory. + +Capture:: The interface with the capture engine. Source code in the +root directory. + +Dumpcap:: The capture engine itself. This is the only part that is to execute +with elevated privileges. Source code in the root directory. + +WinPcap and libpcap:: These are separate libraries that provide packet capture +and filtering support on different platforms. The filtering WinPcap and libpcap +works at a much lower level than Wireshark's display filters and uses a +significantly different mechanism. That's why we have different display and +capture filter syntaxes. + + +[[ChWorksCapturePackets]] + +=== Capturing packets + +Capturing takes packets from a network adapter and saves them to a file +on your hard disk. + +Since raw network adapter access requires elevated privileges these functions +are isolated into the `dumpcap` program. It's only this program that needs these +privileges, allowing the main part of the code (dissectors, user interface, +etc) to run with normal user privileges. + +To hide all the low-level machine dependent details from Wireshark, the libpcap +and WinPcap (see <>) libraries is used. These libraries provide a +general purpose interface to capture packets and are used by a wide variety of +applications. + +[[ChWorksCaptureFiles]] + +=== Capture Files + +Wireshark can read and write capture files in its natural file formats, pcapng +and pcap, which are used by many other network capturing tools, such as tcpdump. +In addition to this, as one of its strengths, Wireshark can read and write files +in many different file formats of other network capturing tools. The wiretap +library, developed together with Wireshark, provides a general purpose interface +to read and write all the file formats. If you need to add support for another +capture file format this is the place to start. + +[[ChWorksDissectPackets]] + +=== 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. + +++++++++++++++++++++++++++++++++++++++ + +++++++++++++++++++++++++++++++++++++++ + diff --git a/docbook/wsdg_src/WSDG_chapter_works.xml b/docbook/wsdg_src/WSDG_chapter_works.xml deleted file mode 100644 index 7a222e31a7..0000000000 --- a/docbook/wsdg_src/WSDG_chapter_works.xml +++ /dev/null @@ -1,168 +0,0 @@ - - - - - How Wireshark Works - -
- Introduction - - This chapter will give you a short overview of how Wireshark works. - -
- -
- Overview - - The following will give you a simplified overview of Wireshark's function blocks: -
- - <application>Wireshark</application> function blocks. - - -
- - - The function blocks in more detail: - - GTK+ 2 - - - Handling of all user input/output (all windows, dialogs and such). - Source code can be found in the gtk directory. - - - - Core - - - Main "glue code" that holds the other blocks together. Source - code can be found in the root directory. - - - - Epan - - - Ethereal Packet ANalyzer - the packet analyzing engine. - Source code can be found in the epan directory. - - - - - Protocol-Tree - Keep data of the capture file protocol information. - - - - - Dissectors - The various protocol dissectors in - epan/dissectors. - - - - - Dissector-Plugins - Some of the protocol dissectors are implemented - as plugins. Source code can be found in plugins. - - - - - Display-Filters - the display filter engine at - epan/dfilter. - - - - - - Wiretap - - - The wiretap library is used to read/write capture files in libpcap - and a lot of other file formats. Source code in the - wiretap directory. - - - - Capture - - - The interface with the capture engine. Source code in the - root directory. - - - - Dumpcap - - - The capture engine itself. This is the only part that is to execute - with elevated privileges. Source code in the root directory. - - - - - WinPcap / libpcap (not part of the Wireshark package) - - - The platform dependent packet capture library, including the capture - filter engine. That's the reason why we still have different display - and capture filter syntax, as two different filtering engines are used. - - - - - -
- -
- Capturing packets - - Capturing will take packets from a network adapter, and save them to a file - on your harddisk. - - - Since raw network adapter access requires elevated privileges these functions - are isolated into the dumpcap program. It's only this program that needs these - privileges, allowing the main part of the code (dissectors, user interface, - etc) to run as normal user program. - - - To hide all the lowlevel machine dependent details from - Wireshark, the libpcap/WinPcap (see ) library - is used. This library provides a general purpose interface to capture - packets from a lot of different network interface types (Ethernet, - Token Ring, ...). - -
- -
- 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 - Wireshark, 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. - -
- -
- 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. - -
- - -