forked from osmocom/wireshark
648 lines
21 KiB
Plaintext
648 lines
21 KiB
Plaintext
// 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
|