forked from osmocom/wireshark
569 lines
19 KiB
Plaintext
569 lines
19 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://wiki.wireshark.org/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:
|
||
link:$$https://wiki.wireshark.org/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 build 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
|
||
|_preferences_|Settings from the Preferences dialog box.
|
||
|_recent_|Recent GUI settings (e.g. recent files lists).
|
||
|_cfilters_|Capture filters.
|
||
|_dfilters_|Display filters.
|
||
|_colorfilters_|Coloring rules.
|
||
|_+++disabled_protos+++_|Disabled protocols.
|
||
|_ethers_|Ethernet name resolution.
|
||
|_manuf_|Ethernet name resolution.
|
||
|_hosts_|IPv4 and IPv6 name resolution.
|
||
|_services_|Network services.
|
||
|_subnets_|IPv4 subnet name resolution.
|
||
|_ipxnets_|IPX name resolution.
|
||
|_vlans_|VLAN ID name resolution.
|
||
|===============
|
||
|
||
[float]
|
||
===== File contents
|
||
|
||
_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 various GUI related settings like the main window position
|
||
and size, the recent files list and such. It is a simple text file containing
|
||
statements of the form:
|
||
+
|
||
--
|
||
----
|
||
variable: value
|
||
----
|
||
|
||
It is read at program start and written at program exit.
|
||
--
|
||
|
||
_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.
|
||
--
|
||
|
||
_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 capture filters are written to the personal display
|
||
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.
|
||
|
||
Wwhen you press the Save button in the ``Coloring Rules'' dialog box,
|
||
all the current color filters are written to the personal color 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 an 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.
|
||
+
|
||
--
|
||
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.
|
||
--
|
||
|
||
_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 the first three bytes of
|
||
an Ethernet address into a manufacturers name. This file has the same
|
||
format as the ethers file, except addresses are three bytes long.
|
||
+
|
||
--
|
||
An example is:
|
||
|
||
----
|
||
00:00:01 Xerox # XEROX CORPORATION
|
||
----
|
||
|
||
The settings from this file are read in at program start 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.
|
||
--
|
||
|
||
_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.
|
||
--
|
||
|
||
_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.
|
||
--
|
||
|
||
_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.
|
||
--
|
||
|
||
_vlans_::
|
||
Wireshark uses the _vlans_ file to translate VLAN tag IDs into names.
|
||
+
|
||
At program start, if there is a _vlans_ file in the personal
|
||
configuration folder, it is read.
|
||
+
|
||
--
|
||
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 and 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 library (libwireshark, libwscodecs
|
||
and libwiretap). 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, Windows Server 2003, and Windows 2000 footnoteref:[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.
|
||
|
||
Windows NT 4 footnoteref:[historical]::
|
||
_C:\WINNT\Profiles{backslash}**username**\Application Data\Wireshark_
|
||
|
||
Windows ME, Windows 98 with user profiles footnoteref:[historical]::
|
||
In Windows ME and 98 you could enable separate user profiles. In that case,
|
||
something like _C:\windows\Profiles{backslash}**username**\Application Data\Wireshark_
|
||
is used.
|
||
|
||
Windows ME, Windows 98 without user profiles footnoteref:[historical]::
|
||
Without user profiles enabled the default location for all users was
|
||
_C:\windows\Application Data\Wireshark_.
|
||
|
||
[[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, Windows Server 2003, Windows 2000 footnoteref:[historical]::
|
||
_C:\Documents and Settings{backslash}**username**\Local Settings\Temp_
|
||
|
||
Windows NT footnoteref:[historical]::
|
||
_C:\TEMP_
|
||
|
||
// End of WSUG Appendix Files
|