diff options
| -rw-r--r-- | docbook/CMakeLists.txt | 9 | ||||
| -rw-r--r-- | docbook/Makefile.common | 9 | ||||
| -rw-r--r-- | docbook/asciidoc.conf | 1 | ||||
| -rw-r--r-- | docbook/wsug_src/WSUG_app_howitworks.asciidoc | 80 | ||||
| -rw-r--r-- | docbook/wsug_src/WSUG_app_howitworks.xml | 105 | ||||
| -rw-r--r-- | docbook/wsug_src/WSUG_app_messages.asciidoc | 85 | ||||
| -rw-r--r-- | docbook/wsug_src/WSUG_app_messages.xml | 107 | ||||
| -rw-r--r-- | docbook/wsug_src/WSUG_app_protocols.asciidoc | 19 | ||||
| -rw-r--r-- | docbook/wsug_src/WSUG_app_protocols.xml | 14 |
9 files changed, 197 insertions, 232 deletions
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 @@ +++++++++++++++++++++++++++++++++++++++ +<!-- WSUG Appendix How it Works --> +++++++++++++++++++++++++++++++++++++++ + +[[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 +<<ChAdvProtocolDissectionSection>> for details. + +++++++++++++++++++++++++++++++++++++++ +<!-- End of WSUG Appendix How it Works --> +++++++++++++++++++++++++++++++++++++++
\ 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 @@ -<!-- WSUG Appendix How it Works --> - -<appendix id="AppHowItWorks"> - <title>How Wireshark Works</title> - <para> - 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. - </para> - - <section><title>Program start</title> - <para> - When Wireshark starts, a lot of things are done: - <itemizedlist> - <listitem> - initialize the dissectors (register the protocol tree), including plugins - </listitem> - <listitem> - load and set values from the preferences file - </listitem> - <listitem> - load the capture filters from the cfilters file - </listitem> - <listitem> - load the display filters from the dfilters file - </listitem> - <listitem> - load and set the disabled protocols from the disabled_protos file - </listitem> - <listitem> - init libpcap/winpcap (the capturing engine) - </listitem> - <listitem> - process command line parameters - </listitem> - <listitem> - load and set the recently used GUI settings from the recent file - </listitem> - <listitem> - init and show the main screen - </listitem> - <listitem> - if specified by command line, load a capture file or start capturing - </listitem> - </itemizedlist> - </para> - <para> - - </para> - </section> - - <section><title>Protocol dissectors</title> - <para> - 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. - </para> - <para> - So Wireshark will dissect a packet from the lowest to the highest protocol - layers. - </para> - <para> - But how does Wireshark know, which dissector to choose? - </para> - <para> - 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: - <itemizedlist> - <listitem> - <command>static</command> 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). - </listitem> - <listitem> - <command>heuristic</command> 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. - </listitem> - </itemizedlist> - </para> - <para> - 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. - </para> - <para> - You can control the way Wireshark calls its dissectors, see <xref - linkend="ChAdvProtocolDissectionSection"/> for details. - </para> - </section> - -</appendix> -<!-- End of WSUG Appendix How it Works --> 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 @@ +++++++++++++++++++++++++++++++++++++++ +<!-- WSUG Appendix Messages --> +++++++++++++++++++++++++++++++++++++++ + +[[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 <<ChAdvReassemblySection>> 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 <<ChCapCaptureOptions>>. 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. + +++++++++++++++++++++++++++++++++++++++ +<!-- End of WSUG Appendix Messages --> +++++++++++++++++++++++++++++++++++++++
\ 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 @@ -<!-- WSUG Appendix Messages --> - -<appendix id="AppMessages"> - <title>Wireshark Messages</title> - <para> - 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. - </para> - <section id="AppMessagesList"><title>Packet List Messages</title> - <para> - These messages might appear in the packet list. - </para> - <section><title>[Malformed Packet]</title> - <para> - Malformed packet means that the protocol dissector can't dissect the - contents of the packet any further. There can be various reasons: - <itemizedlist> - <listitem> - <para> - <command>Wrong dissector</command>: - 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. - </para> - </listitem> - <listitem> - <para> - <command>Packet not reassembled</command>: - The packet is longer than a single frame and it is not reassembled, - see <xref linkend="ChAdvReassemblySection"/> for further details. - </para> - </listitem> - <listitem> - <para> - <command>Packet is malformed</command>: - The packet is actually wrong (malformed), meaning that a part of the - packet is just not as expected (not following the protocol - specifications). - </para> - </listitem> - <listitem> - <para> - <command>Dissector is buggy</command>: - The corresponding protocol dissector is simply buggy or still - incomplete. - </para> - </listitem> - </itemizedlist> - </para> - <para> - 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. - </para> - </section> - <section><title>[Packet size limited during capture]</title> - <para> - The packet size was limited during capture, see "Limit each packet to n - bytes" at the <xref linkend="ChCapCaptureOptions"/>. - 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. - </para> - </section> - </section> - - <section id="AppMessagesDetails"><title>Packet Details Messages</title> - <para> - These messages might appear in the packet details. - </para> - <section><title>[Response in frame: 123]</title> - <para> - 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. - </para> - </section> - <section><title>[Request in frame: 123]</title> - <para> - Same as "Response in frame: 123" above, but the other way round. - </para> - </section> - <section><title>[Time from request: 0.123 seconds]</title> - <para> - The time between the request and the response packets. - </para> - </section> - <section><title>[Stream setup by PROTOCOL (frame 123)]</title> - <para> - 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. - </para> - </section> - </section> - -</appendix> -<!-- End of WSUG Appendix Messages --> 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 @@ +++++++++++++++++++++++++++++++++++++++ +<!-- WSUG Appendix Protocols --> +++++++++++++++++++++++++++++++++++++++ + +[[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:[]] + +++++++++++++++++++++++++++++++++++++++ +<!-- End of WSUG Appendix Protocols --> +++++++++++++++++++++++++++++++++++++++
\ 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 @@ -<!-- WSUG Appendix Protocols --> - -<appendix id="AppProtocols"> - <title>Protocols and Protocol Fields</title> - <para> - Wireshark distinguishes between protocols (e.g. tcp) and protocol fields - (e.g. tcp.port). - </para> - <para> - A comprehensive list of all protocols and protocol fields can be found - at: <ulink url="&WiresharkProtocolsPage;">&WiresharkProtocolsPage;</ulink> - </para> -</appendix> -<!-- End of WSUG Appendix Protocols --> |