From f8f915c2480d47bea33c35f48c18107bae8529a6 Mon Sep 17 00:00:00 2001 From: Gerald Combs Date: Sun, 9 Nov 2014 10:07:46 -0800 Subject: WSUG: Convert ``Protocols'', ``Messages'', and ``How Wireshark Works'' to AsciiDoc. ``How Wireshark Works'' is disabled, so its final output hasn't been checked. Leave most of the content intact for now. Change-Id: Ia78951faa3ffd9c6d2e23067dbfb954ab4042f60 Reviewed-on: https://code.wireshark.org/review/5210 Reviewed-by: Gerald Combs --- docbook/CMakeLists.txt | 9 ++- docbook/Makefile.common | 9 ++- docbook/asciidoc.conf | 1 + docbook/wsug_src/WSUG_app_howitworks.asciidoc | 80 +++++++++++++++++++ docbook/wsug_src/WSUG_app_howitworks.xml | 105 ------------------------- docbook/wsug_src/WSUG_app_messages.asciidoc | 85 ++++++++++++++++++++ docbook/wsug_src/WSUG_app_messages.xml | 107 -------------------------- docbook/wsug_src/WSUG_app_protocols.asciidoc | 19 +++++ docbook/wsug_src/WSUG_app_protocols.xml | 14 ---- 9 files changed, 197 insertions(+), 232 deletions(-) create mode 100644 docbook/wsug_src/WSUG_app_howitworks.asciidoc delete mode 100644 docbook/wsug_src/WSUG_app_howitworks.xml create mode 100644 docbook/wsug_src/WSUG_app_messages.asciidoc delete mode 100644 docbook/wsug_src/WSUG_app_messages.xml create mode 100644 docbook/wsug_src/WSUG_app_protocols.asciidoc delete mode 100644 docbook/wsug_src/WSUG_app_protocols.xml diff --git a/docbook/CMakeLists.txt b/docbook/CMakeLists.txt index 26da16dcff..65cec32dfa 100644 --- a/docbook/CMakeLists.txt +++ b/docbook/CMakeLists.txt @@ -33,9 +33,9 @@ set(COMMON_GRAPHICS set(WSUG_FILES WSUG_app_files.xml - wsug_src/WSUG_app_howitworks.xml - wsug_src/WSUG_app_messages.xml - wsug_src/WSUG_app_protocols.xml + WSUG_app_howitworks.xml + WSUG_app_messages.xml + WSUG_app_protocols.xml wsug_src/WSUG_app_tools.xml WSUG_chapter_advanced.xml WSUG_chapter_build_install.xml @@ -55,6 +55,9 @@ set(WSUG_FILES set(WSDG_ASCIIDOC_FILES wsug_src/WSUG_app_files.asciidoc + wsug_src/WSUG_app_howitworks.asciidoc + wsug_src/WSUG_app_protocols.asciidoc + wsug_src/WSUG_app_messages.asciidoc wsug_src/WSUG_chapter_advanced.asciidoc wsug_src/WSUG_chapter_build_install.asciidoc wsug_src/WSUG_chapter_capture.asciidoc diff --git a/docbook/Makefile.common b/docbook/Makefile.common index 40ca1342e1..05ffcd209f 100644 --- a/docbook/Makefile.common +++ b/docbook/Makefile.common @@ -2,9 +2,9 @@ WSUG_FILES = \ wsug_src/WSUG_app_files.asciidoc \ - wsug_src/WSUG_app_howitworks.xml \ - wsug_src/WSUG_app_messages.xml \ - wsug_src/WSUG_app_protocols.xml \ + wsug_src/WSUG_app_howitworks.asciidoc \ + wsug_src/WSUG_app_messages.asciidoc \ + wsug_src/WSUG_app_protocols.asciidoc \ wsug_src/WSUG_app_tools.xml \ wsug_src/WSUG_chapter_advanced.asciidoc \ wsug_src/WSUG_chapter_build_install.asciidoc \ @@ -23,6 +23,9 @@ WSUG_FILES = \ WSUG_GENERATED_SOURCE = \ wsug_src/WSUG_app_files.xml \ + wsug_src/WSUG_app_howitworks.xml \ + wsug_src/WSUG_app_messages.xml \ + wsug_src/WSUG_app_protocols.xml \ wsug_src/WSUG_chapter_advanced.xml \ wsug_src/WSUG_chapter_build_install.xml \ wsug_src/WSUG_chapter_capture.xml \ diff --git a/docbook/asciidoc.conf b/docbook/asciidoc.conf index 8785940465..d67e3ab41d 100644 --- a/docbook/asciidoc.conf +++ b/docbook/asciidoc.conf @@ -14,6 +14,7 @@ wireshark-code-review-url:\[\]=https://code.wireshark.org/review wireshark-dev-list-email:\[\]=wireshark-dev[AT]wireshark.org wireshark-developers-guide-url:\[\]=https://www.wireshark.org/docs/ wireshark-download-page:\[\]=https://www.wireshark.org/download.html +wireshark-display-filter-reference:\[\]=https://www.wireshark.org/docs/dfref/ wireshark-faq-url:\[\]=https://www.wireshark.org/faq.html wireshark-git-anonhttp-url:\[\]=https://code.wireshark.org/review/wireshark wireshark-git-http-url:\[\]=https://your.username@code.wireshark.org/review/wireshark diff --git a/docbook/wsug_src/WSUG_app_howitworks.asciidoc b/docbook/wsug_src/WSUG_app_howitworks.asciidoc new file mode 100644 index 0000000000..969598ecba --- /dev/null +++ b/docbook/wsug_src/WSUG_app_howitworks.asciidoc @@ -0,0 +1,80 @@ +++++++++++++++++++++++++++++++++++++++ + +++++++++++++++++++++++++++++++++++++++ + +[[AppHowItWorks]] + +[appendix] +== How Wireshark Works + +When using such a complex program like Wireshark, it's sometimes useful to +understand the mechanisms and concepts behind the surface. This is an approach +to shed some light on the inner workings of Wireshark. + +=== Program start + +When Wireshark starts, a lot of things are done: + +* Initialize the dissectors (register the protocol tree), including plugins + +* Load and set values from the preferences file + +* Load the capture filters from the cfilters file + +* Load the display filters from the dfilters file + +* Load and set the disabled protocols from the disabled_protos file + +* Init libpcap/winpcap (the capturing engine) + +* Process command line parameters + +* Load and set the recently used GUI settings from the recent file + +* Init and show the main screen + +* If specified by command line, load a capture file or start capturing + +=== Protocol dissectors + +Each protocol has its own protocol dissector. A dissector is called from +Wireshark, if the packet data seems to be of that corresponding protocol. The +dissector will then process the packet data and call back Wireshark if it +couldn't dissect all the data in that packet to do any further dissections. + +So Wireshark will dissect a packet from the lowest to the highest protocol +layers. + +But how does Wireshark know, which dissector to choose? + +At program start, the dissector registers itself at the appropriate place(s). +There are two ways for a dissector to register itself for packet data: + +* _Static_. If the dissector knows a specific value of a lower layer, if can + directly register itself there (e.g. the HTTP dissector ``knows'', that + typically the well known TCP port 80 is used to transport HTTP data). + +* _Heuristic_. If no such well known way exists, the dissector + can register itself for the heuristic mechanism. If a lower layer dissector + has to handle some packet data where no well known way exists, it can + handover the packet to Wireshark's heuristic mechanism. This will ask all + registered upper layer dissectors, if they ``like'' that data. Each of these + dissectors will typically look into the first few bytes of the packet, if it + contains some characteristic data of that protocol. So the dissector can + accept or reject to dissect that packet. + +Let's look at an example. We'll assume, Wireshark loads a TCP/IP/Ethernet +packet. Wireshark will call the Ethernet dissector, which will dissect the +Ethernet related data (usually the first 6+6+2 bytes). Then this dissector calls +back into Wireshark and will pass the rest of the data back to Wireshark. +Wireshark in turn will call the next related dissector, in our case the IP +dissector (because of the value 0x800 in the Ethernet type field). This game +will continue, until no more data has to be dissected, or the data is just +unknown to Wireshark. + +You can control the way Wireshark calls its dissectors, see +<> for details. + +++++++++++++++++++++++++++++++++++++++ + +++++++++++++++++++++++++++++++++++++++ \ No newline at end of file diff --git a/docbook/wsug_src/WSUG_app_howitworks.xml b/docbook/wsug_src/WSUG_app_howitworks.xml deleted file mode 100644 index 5c46054ab6..0000000000 --- a/docbook/wsug_src/WSUG_app_howitworks.xml +++ /dev/null @@ -1,105 +0,0 @@ - - - - How Wireshark Works - - When using such a complex program like Wireshark, it's sometimes useful to - understand the mechanisms and concepts behind the surface. This is an - approach to shed some light on the inner workings of Wireshark. - - -
Program start - - When Wireshark starts, a lot of things are done: - - - initialize the dissectors (register the protocol tree), including plugins - - - load and set values from the preferences file - - - load the capture filters from the cfilters file - - - load the display filters from the dfilters file - - - load and set the disabled protocols from the disabled_protos file - - - init libpcap/winpcap (the capturing engine) - - - process command line parameters - - - load and set the recently used GUI settings from the recent file - - - init and show the main screen - - - if specified by command line, load a capture file or start capturing - - - - - - -
- -
Protocol dissectors - - Each protocol has its own protocol dissector. A dissector is called from - Wireshark, if the packet data seems to be of that corresponding protocol. The - dissector will then process the packet data and call back Wireshark if it - couldn't dissect all the data in that packet to do any further dissections. - - - So Wireshark will dissect a packet from the lowest to the highest protocol - layers. - - - But how does Wireshark know, which dissector to choose? - - - At program start, the dissector registers itself at the appropriate place(s). - There are two ways, how a dissector can register itself for packet data: - - - static if the dissector knows a specific value - of a lower layer, if can directly register itself there (e.g. the HTTP - dissector "knows", that typically the well known TCP port 80 is used to - transport HTTP data). - - - heuristic if no such well known way exists, the dissector - can register itself for the heuristic mechanism. If a lower layer dissector - has to handle some packet data where no well known way exists, it can - handover the packet to Wireshark's heuristic mechanism. This will ask all - registered upper layer dissectors, if they "like" that data. Each of these - dissectors will typically look into the first few bytes of the packet, if it - contains some characteristic data of that protocol. So the dissector can - accept or reject to dissect that packet. - - - - - Let's look at an example: We'll assume, Wireshark loads a TCP/IP/Ethernet - packet. Wireshark will call the Ethernet dissector, which will dissect the - Ethernet related data (usually the first 6+6+2 bytes). Then this dissector - calls back into Wireshark and will pass the rest of the data back to - Wireshark. Wireshark in turn will call the next related dissector, in our case - the IP dissector (because of the value 0x800 in the Ethernet type field). - This game will continue, until no more data has to be dissected, or the data - is just unknown to Wireshark. - - - You can control the way Wireshark calls its dissectors, see for details. - -
- - - diff --git a/docbook/wsug_src/WSUG_app_messages.asciidoc b/docbook/wsug_src/WSUG_app_messages.asciidoc new file mode 100644 index 0000000000..2b09a313ad --- /dev/null +++ b/docbook/wsug_src/WSUG_app_messages.asciidoc @@ -0,0 +1,85 @@ +++++++++++++++++++++++++++++++++++++++ + +++++++++++++++++++++++++++++++++++++++ + +[[AppMessages]] + +[appendix] +== Wireshark Messages + +Wireshark provides you with additional information generated out of the plain +packet data or it may need to indicate dissection problems. Messages generated +by Wireshark are usually placed in square brackets (``[]''). + +[[AppMessagesList]] + +=== Packet List Messages + +These messages might appear in the packet list. + +==== [Malformed Packet] + +Malformed packet means that the protocol dissector can't dissect the contents of +the packet any further. There can be various reasons: + +* __Wrong dissector__: Wireshark erroneously has chosen the wrong protocol + dissector for this packet. This will happen e.g. if you are using a protocol + not on its well known TCP or UDP port. You may try Analyze|Decode As to + circumvent this problem. + +* __Packet not reassembled__: The packet is longer than a single frame and it is + not reassembled, see <> for further details. + +* __Packet is malformed__: The packet is actually wrong (malformed), meaning + that a part of the packet is just not as expected (not following the protocol + specifications). + +* __Dissector is buggy__: The corresponding protocol dissector is simply buggy + or still incomplete. + +Any of the above is possible. You'll have to look into the specific situation to +determine the reason. You could disable the dissector by disabling the protocol +on the Analyze menu and check how Wireshark displays the packet then. You could +(if it's TCP) enable reassembly for TCP and the specific dissector (if possible) +in the Edit|Preferences menu. You could check the packet contents yourself by +reading the packet bytes and comparing it to the protocol specification. This +could reveal a dissector bug. Or you could find out that the packet is indeed +wrong. + +==== [Packet size limited during capture] + +The packet size was limited during capture, see ``Limit each packet to n bytes'' +at the <>. While dissecting, the current protocol dissector +was simply running out of packet bytes and had to give up. There's nothing else +you can do now, except to repeat the whole capture process again with a higher +(or no) packet size limitation. + +[[AppMessagesDetails]] + +=== Packet Details Messages + +These messages might appear in the packet details. + +==== [Response in frame: 123] + +The current packet is the request of a detected request/response pair. You can +directly jump to the corresponding response packet just by double clicking on +this message. + +==== [Request in frame: 123] + +Same as ``Response in frame: 123'' above, but the other way round. + +==== [Time from request: 0.123 seconds] + +The time between the request and the response packets. + +==== [Stream setup by PROTOCOL (frame 123)] + +The session control protocol (SDP, H225, etc) message which signaled the +creation of this session. You can directly jump to the corresponding packet just +by double clicking on this message. + +++++++++++++++++++++++++++++++++++++++ + +++++++++++++++++++++++++++++++++++++++ \ No newline at end of file diff --git a/docbook/wsug_src/WSUG_app_messages.xml b/docbook/wsug_src/WSUG_app_messages.xml deleted file mode 100644 index 67f42974b4..0000000000 --- a/docbook/wsug_src/WSUG_app_messages.xml +++ /dev/null @@ -1,107 +0,0 @@ - - - - Wireshark Messages - - Wireshark provides you with additional information generated out of - the plain packet data or it may need to indicate dissection problems. - Messages generated by Wireshark are usually placed in [] parentheses. - -
Packet List Messages - - These messages might appear in the packet list. - -
[Malformed Packet] - - Malformed packet means that the protocol dissector can't dissect the - contents of the packet any further. There can be various reasons: - - - - Wrong dissector: - Wireshark erroneously has chosen the wrong protocol dissector for - this packet. This will happen e.g. if you are using a protocol - not on its well known TCP or UDP port. You may try Analyze|Decode As - to circumvent this problem. - - - - - Packet not reassembled: - The packet is longer than a single frame and it is not reassembled, - see for further details. - - - - - Packet is malformed: - The packet is actually wrong (malformed), meaning that a part of the - packet is just not as expected (not following the protocol - specifications). - - - - - Dissector is buggy: - The corresponding protocol dissector is simply buggy or still - incomplete. - - - - - - Any of the above is possible. You'll have to look into the specific - situation to determine the reason. - You could disable the dissector by disabling the - protocol on the Analyze menu and check how Wireshark displays the packet - then. You could (if it's TCP) enable reassembly for TCP and the specific - dissector (if possible) in the Edit|Preferences menu. You could check the - packet contents yourself by reading the packet bytes and comparing it to - the protocol specification. This could reveal a dissector bug. Or you - could find out that the packet is indeed wrong. - -
-
[Packet size limited during capture] - - The packet size was limited during capture, see "Limit each packet to n - bytes" at the . - While dissecting, the current protocol - dissector was simply running out of packet bytes and had to give up. - There's nothing else you can do now, except to repeat the whole capture - process again with a higher (or no) packet size limitation. - -
-
- -
Packet Details Messages - - These messages might appear in the packet details. - -
[Response in frame: 123] - - The current packet is the request of a detected request/response pair. - You can directly jump to the corresponding response packet just - by double clicking on this message. - -
-
[Request in frame: 123] - - Same as "Response in frame: 123" above, but the other way round. - -
-
[Time from request: 0.123 seconds] - - The time between the request and the response packets. - -
-
[Stream setup by PROTOCOL (frame 123)] - - The session control protocol (SDP, H225, etc) message which signaled - the creation of this session. You can directly jump to the - corresponding packet just by double clicking on this message. - -
-
- - - diff --git a/docbook/wsug_src/WSUG_app_protocols.asciidoc b/docbook/wsug_src/WSUG_app_protocols.asciidoc new file mode 100644 index 0000000000..22d8efeaa4 --- /dev/null +++ b/docbook/wsug_src/WSUG_app_protocols.asciidoc @@ -0,0 +1,19 @@ +++++++++++++++++++++++++++++++++++++++ + +++++++++++++++++++++++++++++++++++++++ + +[[AppProtocols]] + +[appendix] +== Protocols and Protocol Fields + +Wireshark distinguishes between protocols (e.g. tcp) and protocol fields (e.g. +tcp.port). + +A comprehensive list of all protocols and protocol fields can be found +in the ``Display Filter Reference'' at +link:$$wireshark-display-filter-reference:[]$$[wireshark-display-filter-reference:[]] + +++++++++++++++++++++++++++++++++++++++ + +++++++++++++++++++++++++++++++++++++++ \ No newline at end of file diff --git a/docbook/wsug_src/WSUG_app_protocols.xml b/docbook/wsug_src/WSUG_app_protocols.xml deleted file mode 100644 index eb5a292db6..0000000000 --- a/docbook/wsug_src/WSUG_app_protocols.xml +++ /dev/null @@ -1,14 +0,0 @@ - - - - Protocols and Protocol Fields - - Wireshark distinguishes between protocols (e.g. tcp) and protocol fields - (e.g. tcp.port). - - - A comprehensive list of all protocols and protocol fields can be found - at: &WiresharkProtocolsPage; - - - -- cgit v1.2.3