Adding upstream version 4.2.2.upstream/4.2.2

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 521 insertions, 0 deletions

diff --git a/docbook/wsug_src/wsug_introduction.adoc b/docbook/wsug_src/wsug_introduction.adoc
new file mode 100644
index 00000000..78f32f57
--- /dev/null
+++ b/docbook/wsug_src/wsug_introduction.adoc
@@ -0,0 +1,521 @@
+// WSUG Chapter Introduction
+
+[#ChapterIntroduction]
+
+== Introduction
+
+[#ChIntroWhatIs]
+
+=== What is Wireshark?
+
+Wireshark is a network packet analyzer. A network packet analyzer
+presents captured packet data in as much detail as possible.
+
+You could think of a network packet analyzer as a measuring device for
+examining what’s happening inside a network cable, just like an electrician uses
+a voltmeter for examining what’s happening inside an electric cable (but at a
+higher level, of course).
+
+In the past, such tools were either very expensive, proprietary, or both.
+However, with the advent of Wireshark, that has changed. Wireshark is
+available for free, is open source, and is one of the best packet
+analyzers available today.
+
+[#ChIntroPurposes]
+
+==== Some intended purposes
+
+Here are some reasons people use Wireshark:
+
+*  Network administrators use it to _troubleshoot network problems_
+
+*  Network security engineers use it to _examine security problems_
+
+*  QA engineers use it to _verify network applications_
+
+*  Developers use it to _debug protocol implementations_
+
+*  People use it to _learn network protocol_ internals
+
+Wireshark can also be helpful in many other situations.
+
+[#ChIntroFeatures]
+
+==== Features
+
+The following are some of the many features Wireshark provides:
+
+* Available for _UNIX_ and _Windows_.
+
+* _Capture_ live packet data from a network interface.
+
+* _Open_ files containing packet data captured with tcpdump/WinDump,
+Wireshark, and many other packet capture programs.
+
+* _Import_ packets from text files containing hex dumps of packet data.
+
+* Display packets with _very detailed protocol information_.
+
+* _Save_ packet data captured.
+
+* _Export_ some or all packets in a number of capture file formats.
+
+* _Filter packets_ on many criteria.
+
+* _Search_ for packets on many criteria.
+
+* _Colorize_ packet display based on filters.
+
+* Create various _statistics_.
+
+*  ...and _a lot more!_
+
+However, to really appreciate its power you have to start using it.
+
+<<ChIntroFig1>> shows Wireshark having captured some packets and waiting for you
+to examine them.
+
+[#ChIntroFig1]
+.Wireshark captures packets and lets you examine their contents.
+image::images/ws-main.png[{screenshot-attrs}]
+
+==== Live capture from many different network media
+
+Wireshark can capture traffic from many different network media types,
+including Ethernet, Wireless LAN, Bluetooth, USB, and more. The specific media
+types supported may be limited by several factors, including your hardware
+and operating system. An overview of the supported media types can be found at
+link:{wireshark-wiki-url}CaptureSetup/NetworkMedia[].
+
+==== Import files from many other capture programs
+
+Wireshark can open packet captures from a large number of capture
+programs. For a list of input formats see <<ChIOInputFormatsSection>>.
+
+==== Export files for many other capture programs
+
+Wireshark can save captured packets in many formats, including those used by other
+capture programs. For a list of output formats see <<ChIOOutputFormatsSection>>.
+
+==== Many protocol dissectors
+
+There are protocol dissectors (or decoders, as they are known in other products)
+for a great many protocols: see <<AppProtocols>>.
+
+==== Open Source Software
+
+Wireshark is an open source software project, and is released under the
+{gplv2-url}[GNU General Public License] (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. Because 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!
+
+[#ChIntroNoFeatures]
+
+==== What Wireshark is not
+
+Here are some things Wireshark does not provide:
+
+* Wireshark isn’t an intrusion detection system. It will not warn you when
+  someone does strange things on your network that he/she isn’t allowed to do.
+  However, if strange things happen, Wireshark might help you figure out what is
+  really going on.
+
+* Wireshark will not manipulate things on the network, it will only “measure”
+  things from it. Wireshark doesn’t send packets on the network or do other
+  active things (except domain name resolution, but that can be disabled).
+
+[#ChIntroPlatforms]
+
+=== System Requirements
+
+The amount of resources Wireshark needs depends on your environment and on the
+size of the capture file you are analyzing. The values below should be fine for
+small to medium-sized capture files no more than a few hundred MB. Larger
+capture files will require more memory and disk space.
+
+[NOTE]
+.Busy networks mean large captures
+====
+A busy network can produce huge capture files. Capturing on
+even a 100 megabit network can produce hundreds of megabytes of
+capture data in a short time. A computer with a fast processor, and lots of
+memory and disk space is always a good idea.
+====
+
+If Wireshark runs out of memory it will crash. See
+{wireshark-wiki-url}KnownBugs/OutOfMemory for details and workarounds.
+
+Although Wireshark uses a separate process to capture packets, the packet
+analysis is single-threaded and won’t benefit much from multi-core systems.
+
+==== Microsoft Windows
+
+Wireshark should support any version of Windows that is still within its
+https://windows.microsoft.com/en-us/windows/lifecycle[extended support
+lifetime]. At the time of writing this includes Windows 11, 10,
+Server 2022,
+Server 2019,
+and Server 2016.
+It also requires the following:
+
+* The Universal C Runtime. This is included with Windows 10 and Windows
+  Server 2019 and is installed automatically on earlier versions if
+  Microsoft Windows Update is enabled. Otherwise you must install
+  https://support.microsoft.com/kb/2999226[KB2999226] or
+  https://support.microsoft.com/kb/3118401[KB3118401].
+
+* Any modern 64-bit Intel or Arm processor.
+
+* 500 MB available RAM. Larger capture files require more RAM.
+
+* 500 MB available disk space. Capture files require additional disk space.
+
+* Any modern display. 1280 {multiplication} 1024 or higher resolution is
+  recommended. Wireshark will make use of HiDPI or Retina resolutions if
+  available. Power users will find multiple monitors useful.
+
+* A supported network card for capturing
+
+  - Ethernet. Any card supported by Windows should work. See the wiki pages on
+    link:{wireshark-wiki-url}CaptureSetup/Ethernet[Ethernet capture] and
+    link:{wireshark-wiki-url}CaptureSetup/Offloading[offloading] for issues that
+    may affect your environment.
+
+  - 802.11. See the {wireshark-wiki-url}CaptureSetup/WLAN#Windows[Wireshark
+    wiki page]. Capturing raw 802.11 information may be difficult without
+    special equipment.
+
+  - Other media. See link:{wireshark-wiki-url}CaptureSetup/NetworkMedia[].
+
+Older versions of Windows which are outside Microsoft’s extended lifecycle
+support window are no longer supported. It is often difficult or impossible to
+support these systems due to circumstances beyond our control, such as third
+party libraries on which we depend or due to necessary features that are only
+present in newer versions of Windows such as hardened security or memory
+management.
+
+* Wireshark 4.0 was the last release branch to officially support Windows 8.1 and Windows Server 2012.
+* Wireshark 3.6 was the last release branch to officially support 32-bit Windows.
+* Wireshark 3.2 was the last release branch to officially support Windows 7 and Windows Server 2008 R2.
+* Wireshark 2.2 was the last release branch to support Windows Vista and Windows Server 2008 sans R2
+* Wireshark 1.12 was the last release branch to support Windows Server 2003.
+* Wireshark 1.10 was the last release branch to officially support Windows XP.
+
+See the link:{wireshark-wiki-url}Development/LifeCycle[Wireshark
+release lifecycle] page for more details.
+
+==== macOS
+
+Wireshark supports macOS 10.14 and later.
+Similar to Windows, supported macOS versions depend on third party libraries and on Apple’s requirements.
+Apple Silicon hardware is supported natively starting with version 4.0
+
+// Wireshark 4.0 ships with Qt 6.2.4, which requires macOS 10.14 and later
+// Wireshark 3.6 ships with Qt 5.15, which requires macOS 10.13 and later.
+// Wireshark 3.4, 3.2 and 3.0 ship with Qt 5.12, which requires macOS 10.12 and later.
+// Wireshark 2.6 ships with Qt 5.3, which was the last release to support 10.6: https://wiki.qt.io/New_Features_in_Qt_5.3
+// "Mac OS 10.6 support is deprecated and scheduled for removal in Qt 5.4"
+
+* Wireshark 3.6 was the last release branch to support macOS 10.13.
+* Wireshark 3.4 was the last release branch to support macOS 10.12.
+* Wireshark 2.6 was the last release branch to support Mac OS X 10.6 and 10.7 and OS X 10.8 to 10.11.
+* Wireshark 2.0 was the last release branch to support OS X on 32-bit Intel.
+* Wireshark 1.8 was the last release branch to support Mac OS X on PowerPC.
+
+The system requirements should be comparable to the specifications listed above for Windows.
+
+==== UNIX, Linux, and BSD
+
+Wireshark runs on most UNIX and UNIX-like platforms including Linux and most BSD variants.
+The system requirements should be comparable to the specifications listed above for Windows.
+
+Binary packages are available for most Unices and Linux distributions
+including the following platforms:
+
+* Alpine Linux
+
+* Arch Linux
+
+* Canonical Ubuntu
+
+* Debian GNU/Linux
+
+* FreeBSD
+
+* Gentoo Linux
+
+* HP-UX
+
+* NetBSD
+
+* OpenPKG
+
+* Oracle Solaris
+
+* Red Hat Enterprise Linux / CentOS / Fedora
+
+If a binary package is not available for your platform you can download
+the source and try to build it. Please report your experiences to
+mailto:{wireshark-dev-list-email}[].
+
+[#ChIntroDownload]
+
+=== Where To Get Wireshark
+
+You can get the latest copy of the program from the Wireshark website at {wireshark-download-url}.
+The download page should automatically highlight the appropriate download for your platform and direct you to the nearest mirror.
+Official Windows and macOS installers are signed using trusted certificates on those platforms.
+macOS installers are additionally notarized.
+
+A new Wireshark version typically becomes available every six weeks.
+
+If you want to be notified about new Wireshark releases you should subscribe to the wireshark-announce mailing list.
+You will find more details in <<ChIntroMailingLists>>.
+
+Each release includes a list of file hashes which are sent to the wireshark-announce mailing list and placed in a file named SIGNATURES-_x_._y_._z_.txt.
+Announcement messages are archived at https://www.wireshark.org/lists/wireshark-announce/ and SIGNATURES files can be found at https://www.wireshark.org/download/src/all-versions/.
+Both are GPG-signed and include verification instructions for Windows, Linux, and macOS.
+As noted above, you can also verify downloads on Windows and macOS using the code signature validation features on those systems.
+
+[#ChIntroHistory]
+
+=== A Brief History Of Wireshark
+
+In late 1997 Gerald Combs needed a tool for tracking down network problems
+and wanted to learn more about networking so he started writing Ethereal (the
+original name of the Wireshark project) as a way to solve both problems.
+
+Ethereal was initially released after several pauses in development in July
+1998 as version 0.2.0. Within days patches, bug reports, and words of
+encouragement started arriving and Ethereal was on its way to success.
+
+Not long after that Gilbert Ramirez saw its potential and contributed a
+low-level dissector to it.
+
+In October, 1998 Guy Harris was looking for something better than tcpview so he
+started applying patches and contributing dissectors to Ethereal.
+
+In late 1998 Richard Sharpe, who was giving TCP/IP courses, saw its potential
+on such courses and started looking at it to see if it supported the protocols
+he needed. While it didn’t at that point new protocols could be easily added.
+So he started contributing dissectors and contributing patches.
+
+The list of people who have contributed to the project has become very long
+since then, and almost all of them started with a protocol that they needed that
+Wireshark did not already handle. So they copied an existing dissector and
+contributed the code back to the team.
+
+In 2006 the project moved house and re-emerged under a new name: Wireshark.
+
+In 2008, after ten years of development, Wireshark finally arrived at version
+1.0. This release was the first deemed complete, with the minimum features
+implemented. Its release coincided with the first Wireshark Developer and User
+Conference, called Sharkfest.
+
+In 2015 Wireshark 2.0 was released, which featured a new user interface.
+
+In 2023 Wireshark moved to the link:{wireshark-foundation-url}[Wireshark Foundation], a nonprofit corporation that operates under section 501(c)(3) of the U.S. tax code.
+The foundation provides the project's infrastructure, hosts link:{sharkfest-url}[SharkFest], our developer and user conference, and promotes low level network education.
+
+[#ChIntroMaintenance]
+
+=== Development And Maintenance Of Wireshark
+
+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 dissectors to Wireshark, and it is expected that this will
+continue. You can find a list of the people who have contributed code to
+Wireshark by checking the about dialog box of Wireshark, or at the
+link:{wireshark-authors-url}[authors] page on the Wireshark web site.
+
+Wireshark is an open source software project, and is released under the
+{gplv2-url}[GNU General Public License] (GPL) version 2. All source code is
+freely available under the GPL. 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:
+
+. 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 you.
+
+. The developers of Wireshark can further improve your changes or implement
+  additional features on top of your code, which may also benefit you.
+
+. The maintainers and developers of Wireshark will maintain your code,
+  fixing it when API changes or other changes are made, and generally keeping it
+  in tune with what is happening with Wireshark. So when Wireshark is updated
+  (which is often), you can get a new Wireshark version from the website
+  and your changes will already be included without any additional effort from you.
+
+The Wireshark source code and binary kits for some platforms are all
+available on the download page of the Wireshark website:
+{wireshark-download-url}.
+
+[#ChIntroHelp]
+
+=== Reporting Problems And Getting Help
+
+If you have problems or need help with Wireshark there are several places that
+may be of interest (besides this guide, of course).
+
+[#ChIntroHomepage]
+
+==== Website
+
+You will find lots of useful information on the Wireshark homepage at
+{wireshark-main-url}.
+
+[#ChIntroWiki]
+
+==== Wiki
+
+The Wireshark Wiki at {wireshark-wiki-url} provides a
+wide range of information related to Wireshark and packet capture in general.
+You will find a lot of information not part of this user’s guide. For example,
+it contains an explanation how to capture on a switched network, an ongoing effort
+to build a protocol reference, protocol-specific information, and much more.
+
+And best of all, if you would like to contribute your knowledge on a specific
+topic (maybe a network protocol you know well), you can edit the wiki pages
+with your web browser.
+
+[#ChIntroQA]
+
+==== Q&amp;A Site
+
+The Wireshark Q&amp;A site at {wireshark-qa-url} offers a resource where
+questions and answers come together. You can search for
+questions asked before and see what answers were given by people who
+knew about the issue. Answers are ranked, so you can easily pick out the best
+ones. If your question hasn’t been discussed before you can post
+one yourself.
+
+[#ChIntroFAQ]
+
+==== FAQ
+
+The Frequently Asked Questions lists often asked questions and their
+corresponding answers.
+
+[NOTE]
+.Read the FAQ
+====
+Before sending any mail to the mailing lists below, be sure to read the FAQ. It
+will often answer any questions 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 dialog shown.
+
+An online version is available at the Wireshark website at
+{wireshark-faq-url}. You might prefer this online version, as it’s
+typically more up to date and the HTML format is easier to use.
+
+[#ChIntroMailingLists]
+
+==== Mailing Lists
+
+There are several mailing lists of specific Wireshark topics available:
+
+link:{wireshark-mailing-lists-url}wireshark-announce[wireshark-announce]::
+    Information about new program releases, which usually appear about every six weeks.
+
+link:{wireshark-mailing-lists-url}wireshark-users[wireshark-users]::
+    Topics of interest to users of Wireshark.
+    People typically post questions about using Wireshark and others (hopefully) provide answers.
+
+link:{wireshark-mailing-lists-url}wireshark-dev[wireshark-dev]::
+    Topics of interest to developers of Wireshark.
+    If you want to develop a protocol dissector or update the user interface, join this list.
+
+You can subscribe to each of these lists from the Wireshark web site:
+{wireshark-mailing-lists-url}. From there, you can choose which mailing
+list you want to subscribe to by clicking on the
+Subscribe/Unsubscribe/Options button under the title of the relevant
+list.  The links to the archives are included on that page as well.
+
+[TIP]
+.The lists are archived
+====
+You can search in the list archives to see if someone asked the same question
+some time before and maybe already got an answer. That way you don’t have to
+wait until someone answers your question.
+====
+
+==== Reporting Problems
+
+[NOTE]
+====
+Before reporting any problems, please make sure you have installed the latest
+version of Wireshark.
+====
+
+
+When reporting problems with Wireshark please supply the following information:
+
+. The version number of Wireshark and the dependent libraries linked with it,
+  such as Qt or GLib. You can obtain this from Wireshark’s about box or the
+  command _wireshark -v_.
+
+. Information about the platform you run Wireshark on
+(Windows, Linux, etc. and 32-bit, 64-bit, etc.).
+
+. A detailed description of your problem.
+
+. If you get an error/warning message, copy the text of that message (and also a
+  few lines before and after it, if there are some) so others may find the
+  place where things go wrong. Please don’t give something like: “I get a
+  warning while doing x” as this won’t give a good idea where to look.
+
+[WARNING]
+.Don’t send confidential information!
+====
+If you send capture files to the mailing lists be sure they don’t contain any
+sensitive or confidential information like passwords or personally identifiable
+information (PII).
+
+In many cases you can use a tool like link:https://www.tracewrangler.com/[TraceWrangler] to sanitize a capture file before sharing it.
+====
+
+[NOTE]
+.Don’t send large files
+====
+Do not send large files (> 1 MB) to the mailing lists. Instead, provide a
+download link. For bugs and feature requests, you can create an issue on
+link:{wireshark-bugs-url}[GitLab Issues] and upload the file there.
+====
+
+==== Reporting Crashes on UNIX/Linux platforms
+
+When reporting crashes with Wireshark it is helpful if you supply the traceback
+information along with the information mentioned in “Reporting Problems”.
+
+You can obtain this traceback information with the following commands on UNIX or
+Linux (note the backticks):
+
+----
+$ gdb `whereis wireshark | cut -f2 -d: | cut -d' ' -f2` core >& backtrace.txt
+backtrace
+^D
+----
+
+If you do not have _gdb_ available, you will have to check out your operating system’s debugger.
+
+Email _backtrace.txt_ to mailto:{wireshark-dev-list-email}[].
+
+==== Reporting Crashes on Windows platforms
+
+The Windows distributions don’t contain the symbol files (.pdb) because they are
+very large. You can download them separately at
+{wireshark-main-url}download/win64/all-versions/ .
+
+// End of WSUG Chapter 1