Adding upstream version 4.2.2.upstream/4.2.2

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

1 files changed, 647 insertions, 0 deletions

diff --git a/docbook/wsug_src/wsug_files.adoc b/docbook/wsug_src/wsug_files.adoc
new file mode 100644
index 00000000..3c4364bb
--- /dev/null
+++ b/docbook/wsug_src/wsug_files.adoc
@@ -0,0 +1,647 @@
+// WSUG Appendix Files
+
+[#AppFiles]
+
+[appendix]
+== Files and Folders
+
+[#ChAppFilesCaptureFilesSection]
+
+=== Capture Files
+
+To understand which information will remain available after the captured packets
+are saved to a capture file, it’s helpful to know a bit about the capture file
+contents.
+
+Wireshark uses the
+link:https://github.com/pcapng/pcapng[pcapng] file
+format as the default format to save captured packets. It is very flexible
+but other tools may not support it.
+
+Wireshark also supports the
+link:https://gitlab.com/wireshark/wireshark/-/wikis/Development/LibpcapFileFormat[libpcap] file
+format. This is a much simpler format and is well established. However, it has
+some drawbacks: it’s not extensible and lacks some information that would be
+really helpful (e.g., being able to add a comment to a packet such as “the
+problems start here” would be really nice).
+
+In addition to the libpcap format, Wireshark supports several different capture
+file formats. However, the problems described above also applies for these
+formats.
+
+[#ChIOFileContentSection]
+
+==== Libpcap File Contents
+
+At the start of each libpcap capture file some basic information is stored like
+a magic number to identify the libpcap file format. The most interesting
+information of this file start is the link layer type (Ethernet, 802.11,
+MPLS, etc.).
+
+The following data is saved for each packet:
+
+* The timestamp with millisecond resolution
+
+* The packet length as it was “on the wire”
+
+* The packet length as it’s saved in the file
+
+* The packet’s raw bytes
+
+A detailed description of the libpcap file format can be found at
+https://gitlab.com/wireshark/wireshark/-/wikis/Development/LibpcapFileFormat
+
+[#ChIOFileNotContentSection]
+
+==== Not Saved in the Capture File
+
+You should also know the things that are _not saved_ in capture files:
+
+* Current selections (selected packet, ...)
+
+* Name resolution information. See <<ChAdvNameResolutionSection>> for details
++
+--
+Pcapng files can optionally save name resolution information. Libpcap files
+can’t. Other file formats have varying levels of support.
+--
+
+* The number of packets dropped while capturing
+
+* Packet marks set with “Edit/Mark Packet”
+
+* Time references set with “Edit/Time Reference”
+
+* The current display filter
+
+[#ChConfigurationPluginFolders]
+
+=== Configuration File and Plugin Folders
+
+To match the different policies for Unix-like systems and Windows, and
+different policies used on different Unix-like systems, the folders
+containing configuration files and plugins are different on different
+platforms.  We indicate the location of the top-level folders under
+which configuration files and plugins are stored here, giving them
+placeholder names independent of their actual location, and use those
+names later when giving the location of the folders for configuration
+files and plugins.
+
+[TIP]
+====
+A list of the folders Wireshark actually uses can be found under the _Folders_
+tab in the dialog box shown when you select _About Wireshark_ from the _Help_
+menu.
+====
+
+==== Folders on Windows
+
+_%APPDATA%_ is the personal application data folder, e.g.:
+_C:\Users{backslash}**username**\AppData\Roaming\Wireshark_ (details can be
+found at: <<ChWindowsProfiles>>).
+
+_WIRESHARK_ is the Wireshark program folder, e.g.: _C:\Program
+Files\Wireshark_.
+
+==== Folders on Unix-like systems
+
+_$XDG_CONFIG_HOME_ is the folder for user-specific configuration files.
+It’s usually _$HOME/.config_, where _$HOME_ is the user’s home folder, which
+is usually something such as _/home/**username**_, or
+_/Users/**username**_ on macOS.
+
+If you are using macOS and you are running a copy of Wireshark
+installed as an application bundle, _APPDIR_ is the top-level directory
+of the Wireshark application bundle, which will typically be
+_/Applications/Wireshark.app_.  Otherwise, _INSTALLDIR_ is the top-level
+directory under which reside the subdirectories in which components of
+Wireshark are installed.  This will typically be `/usr` if Wireshark is
+bundled with the system (for example, provided as a package with a Linux
+distribution) and _/usr/local_ if, for example, you’ve built Wireshark
+from source and installed it.
+
+[#ChAppFilesConfigurationSection]
+
+=== Configuration Files
+
+Wireshark uses a number of configuration files while it is running. Some of these
+reside in the personal configuration folder and are used to maintain information
+between runs of Wireshark, while some of them are maintained in system areas.
+
+The content format of the configuration files is the same on all platforms.
+
+On Windows:
+
+* The personal configuration folder for Wireshark is the
+_Wireshark_ sub-folder of that folder, i.e., _%APPDATA%\Wireshark_.
+
+* The global configuration folder for Wireshark is the Wireshark program
+folder and is also used as the system configuration folder.
+
+On Unix-like systems:
+
+* The personal configuration folder is
+_$XDG_CONFIG_HOME/wireshark_.  For backwards compatibility with
+Wireshark before 2.2, if _$XDG_CONFIG_HOME/wireshark_ does not
+exist and _$HOME/.wireshark_ is present, then the latter will be used.
+
+* If you are using macOS and you are running a copy of Wireshark
+installed as an application bundle, the global configuration folder is
+_APPDIR/Contents/Resources/share/wireshark_.  Otherwise, the
+global configuration folder is _INSTALLDIR/share/wireshark_.
+
+* The _/etc_ folder is the system configuration folder.  The folder
+actually used on your system may vary, maybe something like:
+_/usr/local/etc_.
+
+[#AppFilesTabFolders]
+.Configuration files overview
+[options="header"]
+|===
+|File/Folder|Description
+|_cfilters_|Capture filters.
+|_colorfilters_|Coloring rules.
+|__dfilter_buttons__|Display filter buttons.
+|__dfilter_macros__|Display filter macros.
+|_dfilters_|Display filters.
+|__disabled_protos__|Disabled protocols.
+|_ethers_|Ethernet name resolution.
+|_hosts_|IPv4 and IPv6 name resolution.
+|_ipxnets_|IPX name resolution.
+|_manuf_|Ethernet name resolution.
+|_preferences_|Settings from the Preferences dialog box.
+|_recent_|Per-profile GUI settings.
+|__recent_common__|Common GUI settings.
+|_services_|Network services.
+|_ss7pcs_|SS7 point code resolution.
+|_subnets_|IPv4 subnet name resolution.
+|_vlans_|VLAN ID name resolution.
+|===
+
+[discrete]
+===== File contents
+
+cfilters::
++
+--
+This file contains all the capture filters that you have defined and saved. It
+consists of one or more lines, where each line has the following format:
+
+----
+"<filter name>" <filter string>
+----
+
+At program start, if there is a _cfilters_ file in the personal
+configuration folder, it is read.  If there isn’t a _cfilters_ file in
+the personal configuration folder, then, if there is a _cfilters_ file
+in the global configuration folder, it is read.
+
+When you press the Save button in the “Capture Filters” dialog box,
+all the current capture filters are written to the personal capture
+filters file.
+--
+
+colorfilters::
++
+--
+This file contains all the color filters that you have defined and saved. It
+consists of one or more lines, where each line has the following format:
+
+----
+@<filter name>@<filter string>@[<bg RGB(16-bit)>][<fg RGB(16-bit)>]
+----
+
+At program start, if there is a _colorfilters_ file in the personal
+configuration folder, it is read.  If there isn’t a _colorfilters_ file
+in the personal configuration folder, then, if there is a _colorfilters_
+file in the global configuration folder, it is read.
+
+When you press the Save button in the “Coloring Rules” dialog box,
+all the current color filters are written to the personal color filters
+file.
+--
+
+dfilter_buttons::
++
+--
+This file contains all the display filter buttons that you have defined and
+saved. It consists of one or more lines, where each line has the following
+format:
+
+----
+"TRUE/FALSE","<button label>","<filter string>","<comment string>"
+----
+
+where the first field is TRUE if the button is enabled (shown).
+
+At program start, if there is a __dfilter_buttons__ file in the personal
+configuration folder, it is read. If there isn’t a __dfilter_buttons__ file
+in the personal configuration folder, then, if there is a __dfilter_buttons__
+file in the global configuration folder, it is read.
+
+When you save any changes to the filter buttons, all the current display
+filter buttons are written to the personal display filter buttons file.
+--
+
+dfilter_macros::
++
+--
+This file contains all the display filter macros that you have defined and saved.
+It consists of one or more lines, where each line has the following format:
+
+----
+"<macro name>" <filter string>
+----
+
+At program start, if there is a __dfilter_macros__ file in the personal
+configuration folder, it is read. If there isn’t a __dfilter_macros__ file
+in the personal configuration folder, then, if there is a __dfilter_macros__
+file in the global configuration folder, it is read.
+
+When you press the Save button in the "Display Filter Macros" dialog box,
+all the current display filter macros are written to the personal display
+filter macros file.
+
+More information about Display Filter Macros is available in
+<<ChDisplayFilterMacrosSection>>
+--
+
+dfilters::
++
+--
+This file contains all the display filters that you have defined and saved. It
+consists of one or more lines, where each line has the following format:
+
+----
+"<filter name>" <filter string>
+----
+
+At program start, if there is a _dfilters_ file in the personal
+configuration folder, it is read.  If there isn’t a _dfilters_ file in
+the personal configuration folder, then, if there is a _dfilters_ file
+in the global configuration folder, it is read.
+
+When you press the Save button in the “Display Filters” dialog box,
+all the current display filters are written to the personal display
+filters file.
+--
+
+disabled_protos::
++
+--
+Each line in this file specifies a disabled protocol name. The following are
+some examples:
+
+----
+tcp
+udp
+----
+
+At program start, if there is a __disabled_protos__ file in the global
+configuration folder, it is read first.  Then, if there is a
+__disabled_protos__ file in the personal configuration folder, that is
+read; if there is an entry for a protocol set in both files, the setting
+in the personal disabled protocols file overrides the setting in the
+global disabled protocols file.
+
+When you press the Save button in the “Enabled Protocols” dialog box,
+the current set of disabled protocols is written to the personal
+disabled protocols file.
+--
+
+ethers::
++
+--
+When Wireshark is trying to translate a hardware MAC address to
+a name, it consults the _ethers_ file in the personal configuration
+folder first.  If the address is not found in that file, Wireshark
+consults the _ethers_ file in the system configuration folder.
+
+This file has the same format as the _/etc/ethers_ file on some Unix-like systems.
+Each line in these files consists of one hardware address and name separated by
+whitespace. The digits of hardware addresses are separated by colons (:), dashes
+(-) or periods(.). The following are some examples:
+
+----
+ff-ff-ff-ff-ff-ff    Broadcast
+c0-00-ff-ff-ff-ff    TR_broadcast
+00.2b.08.93.4b.a1    Freds_machine
+----
+
+The settings from this file are read in when a MAC address is to be
+translated to a name, and never written by Wireshark.
+--
+
+hosts::
++
+--
+Wireshark uses the entries in the _hosts_ files to translate IPv4 and
+IPv6 addresses into names.
+
+At program start, if there is a _hosts_ file in the global configuration
+folder, it is read first.  Then, if there is a _hosts_ file in the
+personal configuration folder, that is read; if there is an entry for a
+given IP address in both files, the setting in the personal hosts file
+overrides the entry in the global hosts file.
+
+This file has the same format as the usual _/etc/hosts_ file on Unix systems.
+
+An example is:
+
+----
+# Comments must be prepended by the # sign!
+192.168.0.1 homeserver
+----
+
+The settings from this file are read in at program start and never written by
+Wireshark.
+--
+
+ipxnets::
++
+--
+When Wireshark is trying to translate an IPX network number to
+a name, it consults the _ipxnets_ file in the personal configuration
+folder first.  If the address is not found in that file, Wireshark
+consults the _ipxnets_ file in the system configuration folder.
+
+
+An example is:
+----
+C0.A8.2C.00      HR
+c0-a8-1c-00      CEO
+00:00:BE:EF      IT_Server1
+110f             FileServer3
+----
+
+The settings from this file are read in when an IPX network number is to
+be translated to a name, and never written by Wireshark.
+--
+
+manuf::
++
+--
+At program start, if there is a _manuf_ file in the global configuration folder, it is read.
+
+The entries in this file are used to translate MAC address prefixes into short and long manufacturer names.
+Each line consists of a MAC address prefix followed by an abbreviated manufacturer name and the full manufacturer name.
+Prefixes 24 bits long by default and may be followed by an optional length.
+Note that this is not the same format as the _ethers_ file.
+
+Examples are:
+
+----
+00:00:01        Xerox   Xerox Corporation
+00:50:C2:00:30:00/36      Microsof        Microsoft
+----
+
+The settings from this file are read in at program start and never written by Wireshark.
+--
+
+preferences::
++
+--
+This file contains your Wireshark preferences, including defaults for capturing
+and displaying packets. It is a simple text file containing statements of the
+form:
+
+----
+variable: value
+----
+
+At program start, if there is a _preferences_ file in the global
+configuration folder, it is read first.  Then, if there is a
+_preferences_ file in the personal configuration folder, that is read;
+if there is a preference set in both files, the setting in the personal
+preferences file overrides the setting in the global preference file.
+
+If you press the Save button in the “Preferences” dialog box, all the
+current settings are written to the personal preferences file.
+--
+
+recent::
++
+--
+This file contains GUI settings that are specific to the current profile, such as column widths and toolbar visibility.
+It is a simple text file containing statements of the form:
+
+----
+variable: value
+----
+
+It is read at program start and written when preferences are saved and at program exit.
+It is also written and read whenever you switch to a different profile.
+--
+
+recent_common::
++
+--
+This file contains common GUI settings, such as recently opened capture files, recently used filters, and window geometries.
+It is a simple text file containing statements of the form:
+
+----
+variable: value
+----
+
+It is read at program start and written when preferences are saved and at program exit.
+--
+
+services::
++
+--
+Wireshark uses the _services_ files to translate port numbers into names.
+
+At program start, if there is a _services_ file in the global
+configuration folder, it is read first.  Then, if there is a _services_
+file in the personal configuration folder, that is read; if there is an
+entry for a given port number in both files, the setting in the personal
+hosts file overrides the entry in the global hosts file.
+
+An example is:
+
+----
+mydns       5045/udp     # My own Domain Name Server
+mydns       5045/tcp     # My own Domain Name Server
+----
+
+The settings from these files are read in at program start and never
+written by Wireshark.
+--
+
+ss7pcs::
++
+--
+Wireshark uses the _ss7pcs_ file to translate SS7 point codes to node names.
+
+At program start, if there is a _ss7pcs_ file in the personal
+configuration folder, it is read.
+
+Each line in this file consists of one network indicator followed by a dash followed by a point code in decimal and a node name separated by whitespace or tab.
+
+An example is:
+----
+2-1234 MyPointCode1
+----
+
+The settings from this file are read in at program start and never written by
+Wireshark.
+--
+
+subnets::
++
+--
+Wireshark uses the __subnets__ files to translate an IPv4 address into a
+subnet name.  If no exact match from a __hosts__ file or from DNS is
+found, Wireshark will attempt a partial match for the subnet of the
+address.
+
+At program start, if there is a _subnets_ file in the personal
+configuration folder, it is read first.  Then, if there is a _subnets_
+file in the global configuration folder, that is read; if there is a
+preference set in both files, the setting in the global preferences file
+overrides the setting in the personal preference file.
+
+Each line in one of these files consists of an IPv4 address, a subnet
+mask length separated only by a “/” and a name separated by whitespace.
+While the address must be a full IPv4 address, any values beyond the
+mask length are subsequently ignored.
+
+An example is:
+----
+# Comments must be prepended by the # sign!
+192.168.0.0/24 ws_test_network
+----
+
+A partially matched name will be printed as “subnet-name.remaining-address”.
+For example, “192.168.0.1” under the subnet above would be printed as
+“ws_test_network.1”; if the mask length above had been 16 rather than 24, the
+printed address would be “ws_test_network.0.1”.
+
+The settings from these files are read in at program start and never
+written by Wireshark.
+--
+
+vlans::
++
+--
+Wireshark uses the _vlans_ file to translate VLAN tag IDs into names.
+
+If there is a _vlans_ file in the currently active profile folder, it is used. Otherwise, the _vlans_ file in the personal configuration folder is used.
+
+Each line in this file consists of one VLAN tag ID and a describing name separated by whitespace or tab.
+
+An example is:
+----
+123     Server-LAN
+2049    HR-Client-LAN
+----
+
+The settings from this file are read in at program start or when changing
+the active profile and are never written by Wireshark.
+--
+
+[#ChPluginFolders]
+
+=== Plugin folders
+
+Wireshark supports plugins for various purposes.  Plugins can either be
+scripts written in Lua or code written in C or {cpp} and compiled to
+machine code.
+
+Wireshark looks for plugins in both a personal plugin folder and a
+global plugin folder.  Lua plugins are stored in the plugin folders;
+compiled plugins are stored in subfolders of the plugin folders, with
+the subfolder name being the Wireshark minor version number (X.Y). There is
+another hierarchical level for each Wireshark plugin type (libwireshark,
+libwiretap and codecs). So for example the location for a libwireshark plugin
+_foo.so_ (_foo.dll_ on Windows) would be _PLUGINDIR/X.Y/epan_
+(libwireshark used to be called libepan; the other folder names are _codecs_
+and _wiretap_).
+
+On Windows:
+
+* The personal plugin folder is _%APPDATA%\Wireshark\plugins_.
+
+* The global plugin folder is _WIRESHARK\plugins_.
+
+On Unix-like systems:
+
+* The personal plugin folder is _~/.local/lib/wireshark/plugins_.
+
+[NOTE]
+====
+To provide better support for binary plugins this folder changed in Wireshark 2.5.
+It is recommended to use the new folder but *for lua scripts only* you may
+continue to use _$XDG_CONFIG_HOME/wireshark/plugins_ for backward-compatibility.
+This is useful to have older versions of Wireshark installed side-by-side. In case
+of duplicate file names between old and new the new folder wins.
+====
+
+* If you are running on macOS and Wireshark is installed as an
+application bundle, the global plugin folder is
+_%APPDIR%/Contents/PlugIns/wireshark_, otherwise it’s
+_INSTALLDIR/lib/wireshark/plugins_.
+
+[#ChWindowsFolder]
+
+=== Windows folders
+
+Here you will find some details about the folders used in Wireshark on different
+Windows versions.
+
+As already mentioned, you can find the currently used folders in the “About
+Wireshark” dialog.
+
+[#ChWindowsProfiles]
+
+==== Windows profiles
+
+Windows uses some special directories to store user configuration files which
+define the “user profile”. This can be confusing, as the default directory
+location changed from Windows version to version and might also be different for
+English and internationalized versions of Windows.
+
+[NOTE]
+====
+If you’ve upgraded to a new Windows version, your profile might be kept in the
+former location. The defaults mentioned here might not apply.
+====
+
+The following guides you to the right place where to look for Wireshark’s
+profile data.
+
+Windows 10, Windows 8.1, Windows 8, Windows 7, Windows Vista, and associated server editions::
+_C:\Users{backslash}**username**\AppData\Roaming\Wireshark_.
+
+Windows XP and Windows Server 2003 footnote:historical[No longer supported by Wireshark. For historical reference only.]::
+_C:\Documents and Settings{backslash}**username**\Application Data_. “Documents and
+Settings” and “Application Data” might be internationalized.
+
+[#ChWindowsRoamingProfiles]
+
+==== Windows roaming profiles
+
+Some larger Windows environments use roaming profiles. If this is the case the
+configurations of all programs you use won’t be saved on your local hard drive.
+They will be stored on the domain server instead.
+
+Your settings will travel with you from computer to computer with one exception.
+The “Local Settings” folder in your profile data (typically something like:
+_C:\Documents and Settings{backslash}**username**\Local Settings_) will not be
+transferred to the domain server. This is the default for temporary capture
+files.
+
+[#ChWindowsTempFolder]
+
+==== Windows temporary folder
+
+Wireshark uses the folder which is set by the TMPDIR or TEMP environment
+variable. This variable will be set by the Windows installer.
+
+Windows 10, Windows 8.1, Windows 8, Windows 7, Windows Vista, and associated server editions::
+_C:\Users{backslash}**username**\AppData\Local\Temp_
+
+Windows XP and Windows Server 2003 footnote:historical[]::
+_C:\Documents and Settings{backslash}**username**\Local Settings\Temp_
+
+// End of WSUG Appendix Files