WSUG: Clarified and improved phrasing

Change-Id: I1b3b8b7bf5f6460aa779c54881abd53059b26bbb
Reviewed-on: https://code.wireshark.org/review/33606
Reviewed-by: Alexis La Goutte <alexis.lagoutte@gmail.com>
Petri-Dish: Alexis La Goutte <alexis.lagoutte@gmail.com>
Tested-by: Petri Dish Buildbot
Reviewed-by: Anders Broman <a.broman58@gmail.com>
This commit is contained in:
Moshe Kaplan 2019-06-14 19:03:17 -04:00 committed by Anders Broman
parent 17aacfae43
commit c6bed35254
15 changed files with 95 additions and 97 deletions

View File

@ -25,8 +25,9 @@
:wireshark-authors-url: {wireshark-main-url}about.html#authors
:wireshark-buildbot-url: https://buildbot.wireshark.org/wireshark-master/waterfall
:wireshark-code-browse-url: {wireshark-code-review-url}/gitweb?p=wireshark.git
:wireshark-developers-guide-url: {wireshark-main-url}docs/
:wireshark-developers-guide-url: {wireshark-docs-url}wsdg_html_chunked/
:wireshark-display-filter-reference-url: {wireshark-main-url}docs/dfref/
:wireshark-docs-url: {wireshark-main-url}docs/
:wireshark-download-url: {wireshark-main-url}download.html
:wireshark-faq-url: {wireshark-main-url}faq.html
:wireshark-git-anonhttp-url: \https://code.wireshark.org/review/wireshark
@ -35,7 +36,7 @@
:wireshark-mailing-lists-url: {wireshark-main-url}lists/
:wireshark-man-page-url: {wireshark-main-url}docs/man-pages/
:wireshark-snapshots-url: {wireshark-main-url}download/automated/src/
:wireshark-users-guide-url: {wireshark-main-url}docs/
:wireshark-users-guide-url: {wireshark-docs-url}wsug_html_chunked/
// External URLs
:tcpdump-main-url: http://www.tcpdump.org/

View File

@ -71,9 +71,8 @@ It is written in AsciiDoc.
=== Where to get the latest copy of this document?
The latest copy of this documentation can always be found at:
{wireshark-developers-guide-url} in A4 PDF, US letter PDF, single HTML,
and chunked HTML.
The latest copy of this documentation can always be found at
{wireshark-developers-guide-url}.
[[PreFeedback]]

View File

@ -15,7 +15,7 @@ can be used to write dissectors, taps, and capture file readers
and writers.
Wiresharks Lua interpreter starts by loading a file named `init.lua` from
Wireshark's link:{wireshark-users-guide-url}wsug_html_chunked/ChAppFilesConfigurationSection.html[_global configuration directory_].
Wireshark's link:{wireshark-users-guide-url}ChAppFilesConfigurationSection.html[_global configuration directory_].
The _global configuration directory_'s `init.lua` controls whether or not Lua
scripts are enabled via the
_$$enable_lua$$_ variable. Lua scripts are enabled by
@ -26,9 +26,9 @@ _$$disable_lua$$_ are present, _$$disable_lua$$_ is ignored.
If Lua is enabled, Wireshark will try to load a file named `init.lua`
from the users
link:{wireshark-users-guide-url}wsug_html_chunked/ChAppFilesConfigurationSection.html[_personal configuration directory_]
link:{wireshark-users-guide-url}ChAppFilesConfigurationSection.html[_personal configuration directory_]
and all files ending with _.lua_ in the global and the personal
link:{wireshark-users-guide-url}wsug_html_chunked/ChPluginFolders.html[_plugins directory_].
link:{wireshark-users-guide-url}ChPluginFolders.html[_plugins directory_].
The command line option _$$-X lua_script:$$++file.lua++_ can also be used to load
specific Lua scripts.

View File

@ -35,20 +35,19 @@ When Wireshark starts, a lot of things are done:
=== 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
couldnt dissect all the data in that packet to do any further dissections.
Each protocol has its own protocol dissector. When processing network data,
Wireshark calls the dissector that seems relevant to the packet data. The
dissector will then process the packet data and send any unprocessed data
back to Wireshark for further dissection.
So Wireshark will dissect a packet from the lowest to the highest protocol
layers.
But how does Wireshark know, which dissector to choose?
But how does Wireshark know which dissector to use?
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:
When Wireshark starts each dissector registers itself in one of two ways:
* _Static_. If the dissector knows a specific value of a lower layer, if can
* _Static_. If the dissector knows a specific value of a lower layer, it 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).
@ -56,18 +55,18 @@ There are two ways for a dissector to register itself for packet data:
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 Wiresharks 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.
registered upper layer dissectors, if they “like” that data. These
dissectors typically look at the first few bytes of the packet, to see if they
contain some characteristic data of that protocol and then
decide whether or not to dissect that packet.
Lets look at an example. Well 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.
Ethernet related data (usually the first 6 + 6 + 2 bytes). The Ethernet
dissector then passes 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
dissector (because of the value 0x800 in the Ethernet type field). This
will continue until no more data has to be dissected, or the data is
unknown to Wireshark.
You can control the way Wireshark calls its dissectors, see

View File

@ -61,8 +61,8 @@ 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.
directly jump to the corresponding response packet by double clicking on
the message.
==== [Request in frame: 123]
@ -75,7 +75,7 @@ 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
creation of this session. You can directly jump to the corresponding packet
by double clicking on this message.
// End of WSUG Appendix Messages

View File

@ -9,9 +9,9 @@
=== Introduction
Along with the main application, Wireshark comes with an array of
command line tools which can be helpful for specialized tasks. Some of
these tools will be described in this chapter. You can find more
Wireshark comes with an array of
command line tools which can be helpful for packet analysis. Some of
these tools are described in this chapter. You can find more
information about all of Wiresharks command line tools on
link:{wireshark-man-page-url}[the web site].
@ -43,7 +43,7 @@ Older versions of `tcpdump` truncate packets to 68 or 96 bytes. If this is the c
use `-s` to capture full-sized packets:
----
$ tcpdump -i <interface> -s 65535 -w <some-file>
$ tcpdump -i <interface> -s 65535 -w <file>
----
You will have to specify the correct _interface_ and the name of a _file_ to
@ -63,8 +63,8 @@ Dumpcap is a network traffic dump tool. It captures packet data from a live
network and writes the packets to a file. Dumpcaps native capture file format
is pcapng, which is also the format used by Wireshark.
Without any options set it will use the pcap library to capture traffic
from the first available network interface and write the received raw
By default, Dumpcap uses the pcap library to capture traffic
from the first available network interface and writes the received raw
packet data, along with the packets time stamps into a pcapng file. The
capture filter syntax follows the rules of the pcap library. For more
information on `dumpcap` consult your local manual page (`man dumpcap`)
@ -144,7 +144,7 @@ include::editcap-T.txt[]
=== __mergecap__: Merging multiple capture files into one
Mergecap is a program that combines multiple saved capture files into a single
output file specified by the `-w` argument. Mergecap knows how to read libpcap
output file specified by the `-w` argument. Mergecap can read libpcap
capture files, including those of tcpdump. In addition, Mergecap can read
capture files from snoop (including Shomiti) and atmsnoop, LanAlyzer, Sniffer
(compressed or uncompressed), Microsoft Network Monitor, AIXs iptrace, NetXray,
@ -155,9 +155,9 @@ type by itself. Mergecap is also capable of reading any of these file formats if
they are compressed using `gzip`. Mergecap recognizes this directly from the
file; the “.gz” extension is not required for this purpose.
By default, it writes the capture file in pcapng format, and writes all of the
packets in the input capture files to the output file. The `-F` flag can be used
to specify the format in which to write the capture file; it can write the file
By default, Mergecap writes all of the packets in the input capture files to a
pcapng file. The `-F` flag can be used
to specify the capture file's output format ; it can write the file
in libpcap format (standard libpcap format, a modified format used by some
patched versions of libpcap, the format used by Red Hat Linux 6.1, or the format
used by SuSE Linux 6.3), snoop format, uncompressed Sniffer format, Microsoft

View File

@ -15,7 +15,7 @@ This chapter will describe some of Wiresharks advanced features.
=== [[ChAdvFollowTCPSection]]Following Protocol Streams [[ChAdvFollowStreamSection]]
It can be very helpful to see protocol in the way that the application
It can be very helpful to see a protocol in the way that the application
layer sees it. Perhaps you are looking for passwords in a Telnet stream,
or you are trying to make sense of a data stream. Maybe you just need a
display filter to show only the packets in a TLS or SSL stream. If so,

View File

@ -15,19 +15,19 @@ and skip the rest of this chapter.
If you are running another operating system such as Linux or FreeBSD you might
want to install from source. Several Linux distributions offer Wireshark
packages but they commonly ship out-of-date versions. No other versions of UNIX
packages but they commonly provide out-of-date versions. No other versions of UNIX
ship Wireshark so far. For that reason, you will need to know where to get the
latest version of Wireshark and how to install it.
This chapter shows you how to obtain source and binary packages and how to
build Wireshark from source should you choose to do so.
The following are the general steps you would use:
The general steps are the following:
. Download the relevant package for your needs, e.g. source or binary
distribution.
. Compile the source into a binary if needed.
. For source distributions, compile the source into a binary.
This may involve building and/or installing other necessary packages.
. Install the binaries into their final destinations.
@ -44,14 +44,12 @@ select the desired binary or source package.
.Download all required files
====
If you are building Wireshark from source you will
In general, unless you have already downloaded Wireshark before, you will most
likely need to download several source packages if you are building Wireshark
from source. This is covered in more detail below.
likely need to download several other dependencies.
This is covered in detail below.
// Make a ref
====
Once you have downloaded the relevant files, you can go on to the next step.
//
// Windows
@ -182,24 +180,20 @@ Running the installer without any parameters shows the normal interactive instal
==== Manual Npcap Installation
As mentioned above, the Wireshark installer takes care of installing Npcap.
The following is only necessary if you want to use a different version than the
one included in the Wireshark installer, e.g. because a new Npcap version was
released.
Additional Npcap versions (including newer alpha or beta releases) can
be downloaded from the main Npcap site at {npcap-main-url}. The
_Installer for Windows_ supports modern Windows operating systems.
As mentioned above, the Wireshark installer also installs Npcap.
If you prefer to install Npcap manually or want to use a different version than the
one included in the Wireshark installer, you can download Npcap from
the main Npcap site at {npcap-main-url}.
[[ChBuildInstallWinWiresharkUpdate]]
==== Update Wireshark
By default the offical Windows package will check for new versions and notify
The offical Wireshark Windows package will check for new versions and notify
you when they are available. If you have the _Check for updates_ preference
disabled or if you run Wireshark in an isolated environment you should subcribe
to the _wireshark-announce_ mailing list. See <<ChIntroMailingLists>> for
details on subscribing to this list.
to the _wireshark-announce_ mailing list to be notified of new versions.
See <<ChIntroMailingLists>> for details on subscribing to this list.
New versions of Wireshark are usually released every four to six weeks. Updating
Wireshark is done the same way as installing it. Simply download and start the
@ -210,7 +204,8 @@ remain unchanged.
==== Update Npcap
New versions of Npcap. You will find Npcap update instructions the Npcap web
Wireshark updates may also include a new version of Npcap.
Manual Npcap updates instructions can be found on the Npcap web
site at {npcap-main-url}. You may have to reboot your machine after installing
a new Npcap version.
@ -222,8 +217,8 @@ You can uninstall Wireshark using the _Programs and Features_ control panel.
Select the “Wireshark” entry to start the uninstallation procedure.
The Wireshark uninstaller provides several options for removal. The default is
to remove the core components but keep your personal settings.
Npcap is left installed by default in case other programs need it.
to remove the core components but keep your personal settings and Npcap.
Npcap is kept in case other programs need it.
[[ChBuildInstallNpcapUninstall]]
@ -233,6 +228,20 @@ You can uninstall Npcap independently of Wireshark using the _Npcap_ entry
in the _Programs and Features_ control panel. Remember that if you uninstall
Npcap you wont be able to capture anything with Wireshark.
[[ChBuildInstallWinBuild]]
=== Building from source under Windows
We strongly recommended using the binary installer for Windows unless you
want to start developing Wireshark on the Windows platform.
For further information how to build Wireshark for Windows from the sources
see the Developers Guide at {wireshark-developers-guide-url}.
You may also want to have a look at the Development Wiki
({wireshark-wiki-url}Development) for the latest available development
documentation.
//
// macOS
//
@ -418,19 +427,5 @@ _wireshark-dev_ mailing list explaining your problem. Include the output from
`cmake` and anything else you think is relevant such as a trace of the
`make` stage.
[[ChBuildInstallWinBuild]]
=== Building from source under Windows
We strongly recommended that you use the binary installer for Windows unless you
want to start developing Wireshark on the Windows platform.
For further information how to build Wireshark for Windows from the sources
see the Developers Guide at {wireshark-developers-guide-url}.
You may also want to have a look at the Development Wiki
({wireshark-wiki-url}Development) for the latest available development
documentation.
// End of WSUG Chapter 2

View File

@ -67,7 +67,7 @@ The following methods can be used to start capturing packets with Wireshark:
btn:[Start] button.
* You can immediately start a capture using your current settings by selecting
menu:Capture[Start] or by cliking the first toolbar button.
menu:Capture[Start] or by clicking the first toolbar button.
* If you already know the name of the capture interface you can start Wireshark
from the command line:
@ -399,7 +399,7 @@ captured for each packet, and is sometimes referred to as the _snaplen_. If
disabled the value is set to the maximum 65535 which will be sufficient for
most protocols. Some rules of thumb:
* If you are unsure just keep the default value.
* If you are unsure, keep the default value.
* If you dont need or dont want all of the data in a packet - for example, if
you only need the link-layer, IP, and TCP headers - you might want to choose a
@ -430,7 +430,9 @@ associated to.
====
_Capture Filter_::
This field allows you to specify a capture filter. Capture filters are discussed
This field allows you to specify a capture filter. Capture filters can be
used to limit which packets are captured from the interface(s).
Capture filters are discussed
in more details in <<ChCapCaptureFilterSection>>. It defaults to empty, or no
filter.
+
@ -660,7 +662,7 @@ one of the “Multiple files” options. This will spread the captured packets o
several smaller files which can be much more pleasant to work with.
====
Using Multiple files may cut context related information. Wireshark keeps
Using the “Multiple files” option may cut context related information. Wireshark keeps
context information of the loaded packet data, so it can report context related
problems (like a stream error) and keeps information about context related
protocols (e.g. where data is exchanged at the establishing phase and only
@ -710,7 +712,7 @@ _Multiple files, ring buffer_::
=== Link-layer header type
In most cases you wont have to modify link-layer header type. Some exceaptions
In most cases you wont have to modify link-layer header type. Some exceptions
are as follows:
If you are capturing on an Ethernet device you might be offered a choice of
@ -740,10 +742,12 @@ to be read by an application that doesnt support SunATM headers, select “RF
=== Filtering while capturing
Wireshark uses the libpcap filter language for capture filters. A brief
overview of the syntax follows. Complete documentation can be found in
Wireshark supports limiting the packet capture to packets that match a
_capture filter_. Wireshark capture filters are written in
libpcap filter language. Below is a brief overview of the libpcap filter
language's syntax. Complete documentation can be found at
the link:{pcap-filter-man-page-url}[pcap-filter man page]. You can find
a lot of Capture Filter examples at {wireshark-wiki-url}CaptureFilters.
many Capture Filter examples at {wireshark-wiki-url}CaptureFilters.
You enter the capture filter into the “Filter” field of the Wireshark
“Capture Options” dialog box, as shown in <<ChCapCaptureOptionsDialog>>.

View File

@ -157,7 +157,7 @@ discarded so a new file can be written.
+
If the optional <command>duration</command> is specified, Wireshark will also
switch to the next file when the specified number of seconds has elapsed even
if the current file is not completely fills up.
if the current file is not completely filled up.
+
--
duration</command>:value::
@ -565,7 +565,7 @@ Disabling a protocol will prevent information about higher-layer protocols from
being displayed. For example, suppose you disabled the IP protocol and selected
a packet containing Ethernet, IP, TCP, and HTTP information. The Ethernet
information would be displayed, but the IP, TCP and HTTP information would not -
disabling IP would prevent it and the other protocols from being displayed.
disabling IP would prevent it and the higher-layer protocols from being displayed.
====
To enable or disable protocols select menu:Analyze[Enabled Protocols...].
@ -953,7 +953,7 @@ certain pieces of information. In many cases, they are used in an extension
mechanism so that new object identifiers (and associated values) may be defined
without needing to change the base standard.
Whilst Wireshark has knowledge about many of the OIDs and the syntax of their
While Wireshark has knowledge about many of the OIDs and the syntax of their
associated values, the extensibility means that other values may be encountered.
Wireshark uses this table to allow the user to define the name and syntax of

View File

@ -488,7 +488,7 @@ backtrace
If you do not have _gdb_ available, you will have to check out your operating systems debugger.
Mail _backtrace.txt_ to mailto:{wireshark-dev-list-email}[].
Email _backtrace.txt_ to mailto:{wireshark-dev-list-email}[].
==== Reporting Crashes on Windows platforms

View File

@ -129,7 +129,7 @@ Specific for this dialog:
The following file formats from other capture tools can be opened by Wireshark:
* pcapng. A flexible, etensible successor to the libpcap format. Wireshark 1.8 and later
* pcapng. A flexible, extensible successor to the libpcap format. Wireshark 1.8 and later
save files as pcapng by default. Versions prior to 1.8 used libpcap.
* libpcap. The default format used by the _libpcap_ packet capture library. Used
@ -307,7 +307,7 @@ time stamp accuracy; see the <<ChAdvTimestamps>> for details.
The following file formats can be saved by Wireshark (with the known file extensions):
* pcapng ({asterisk}.pcapng). A flexible, etensible successor to the
* pcapng ({asterisk}.pcapng). A flexible, extensible successor to the
libpcap format. Wireshark 1.8 and later save files as pcapng by
default. Versions prior to 1.8 used libpcap.

View File

@ -36,8 +36,8 @@ These statistics range from general information about the loaded capture file
[NOTE]
====
The protocol specific statistics require detailed knowledge about the specific
protocol. Unless you are familiar with that protocol, statistics about it will
be pretty hard to understand.
protocol. Unless you are familiar with that protocol, statistics about it may
be difficult to understand.
====
Wireshark has many other statistics windows that display detailed
@ -388,12 +388,12 @@ different) compared to the following description.
The service response time of DCE-RPC is the time between the request and the
corresponding response.
First of all, you have to select the DCE-RPC interface:
First, you have to select the DCE-RPC interface:
.The “Compute DCE-RPC statistics” window
image::wsug_graphics/ws-stats-srt-dcerpc-filter.png[{screenshot-attrs}]
You can optionally set a display filter, to reduce the amount of packets.
You can optionally set a display filter to reduce the number of packets.
.The “DCE-RPC Statistic for ...” window
image::wsug_graphics/ws-stats-srt-dcerpc.png[{screenshot-attrs}]

View File

@ -8,7 +8,7 @@
=== Introduction
By now you have installed Wireshark and are most likely keen to get started
By now you have installed Wireshark and are likely keen to get started
capturing your first packets. In the next chapters we will explore:
* How the Wireshark user interface works
@ -55,8 +55,8 @@ other GUI programs.
. The _menu_ (see <<ChUseMenuSection>>) is used to start actions.
. The _main toolbar_ (see <<ChUseMainToolbarSection>>) provides quick access to
frequently used items from the menu.
. The _filter toolbar_ (see <<ChUseFilterToolbarSection>>) provides a way to
directly manipulate the currently used display filter (see
. The _filter toolbar_ (see <<ChUseFilterToolbarSection>>) allows users to
set _display filters_ to filter which packets are displayed (see
<<ChWorkDisplayFilterSection>>).
. The _packet list pane_ (see <<ChUsePacketListPaneSection>>) displays a summary
of each packet captured. By clicking on packets in this pane you control what is
@ -169,7 +169,7 @@ including a media analysis, flow diagrams, display protocol hierarchy statistics
and much more. See <<ChUseTelephonyMenuSection>>.
menu:Wireless[]::
The items in this menu show Bluetooth and IEEE 802.11 wireless statistics.
This menu contains items to display Bluetooth and IEEE 802.11 wireless statistics.
menu:Tools[]::
This menu contains various tools available in Wireshark, such as creating
@ -537,7 +537,7 @@ image::wsug_graphics/ws-analyze-menu.png[{screenshot-attrs}]
[options="header",cols="3,2,5"]
|===============
|Menu Item|Accelerator|Description
|menu:Display Filters...[] ||This menu item brings up a dialog box that allows you to create and edit display filters. You can name filters, and you can save them for future use. More detail on this subject is provided in <<ChWorkDefineFilterSection>>
|menu:Display Filters...[] ||This menu item displays a dialog box that allows you to create and edit display filters. You can name filters, and you can save them for future use. More detail on this subject is provided in <<ChWorkDefineFilterSection>>
|menu:Display Filter Macros...[] ||This menu item brings up a dialog box that allows you to create and edit display filter macros. You can name filter macros, and you can save them for future use. More detail on this subject is provided in <<ChWorkDefineFilterMacrosSection>>
|menu:Apply as Column[] ||This menu item adds the selected protocol item in the packet details pane as a column to the packet list.
|menu:Apply as Filter[...] ||These menu items will change the current display filter and apply the changed filter immediately. Depending on the chosen menu item, the current display filter string will be replaced or appended to by the selected protocol field in the packet details pane.

View File

@ -1008,7 +1008,7 @@ with black background, regardless of the coloring rules set. Marking a packet
can be useful to find it later while analyzing in a large capture file.
The packet marks are not stored in the capture file or anywhere else. All
packet marks will be lost when you close the capture file.
packet marks will be lost when the capture file is closed.
You can use packet marking to control the output of packets when saving,
exporting, or printing. To do so, an option in the packet range is available,