path: root/doc/man_pages/files.adoc

== FILES

These files contain various *Wireshark* configuration settings.

Preferences::
+
--
The __preferences__ files contain global (system-wide) and personal
preference settings.  If the system-wide preference file exists, it is
read first, overriding the default settings.  If the personal preferences
file exists, it is read next, overriding any previous values.  Note: If
the command line flag *-o* is used (possibly more than once), it will
in turn override values from the preferences files.

The preferences settings are in the form __prefname:value__,
one per line,
where __prefname__ is the name of the preference
and __value__ is the value to
which it should be set; white space is allowed between *:* and
__value__.  A preference setting can be continued on subsequent lines by
indenting the continuation lines with white space.  A *#* character
starts a comment that runs to the end of the line:

  # Vertical scrollbars should be on right side?
  # TRUE or FALSE (case-insensitive).
  gui.scrollbar_on_right: TRUE

The global preferences file is looked for in the __wireshark__ directory
under the __share__ subdirectory of the main installation directory.  On
macOS, this would typically be
__/Application/Wireshark.app/Contents/Resources/share__; on other
UNIX-compatible systems, such as Linux, \*BSD, Solaris, and AIX, this
would typically be __/usr/share/wireshark/preferences__ for
system-installed packages and __/usr/local/share/wireshark/preferences__
for locally-installed packages; on Windows, this would typically be
__C:\Program Files\Wireshark\preferences__.

On UNIX-compatible systems, the personal preferences file is looked for
in __$XDG_CONFIG_HOME/wireshark/preferences__, (or, if
__$XDG_CONFIG_HOME/wireshark__ does not exist while __$HOME/.wireshark__
does exist, __$HOME/.wireshark/preferences__); this is typically
__$HOME/.config/wireshark/preferences__.  On Windows,
the personal preferences file is looked for in
__%APPDATA%\Wireshark\preferences__ (or, if %APPDATA% isn't defined,
__%USERPROFILE%\Application Data\Wireshark\preferences__).

// tag::gui[]
Note: Whenever the preferences are saved by using the __Save__ button
in the __Edit:Preferences__ dialog box, your personal preferences file
will be overwritten with the new settings, destroying any comments and
unknown/obsolete settings that were in the file.
// end::gui[]
--

// tag::gui[]
Recent::
+
--
The __recent__ file contains personal settings (mostly GUI related) such
as the current *Wireshark* window size.  The file is saved at program exit and
read in at program start automatically.  Note: The command line flag *-o*
may be used to override settings from this file.

The settings in this file have the same format as in the __preferences__
files, and the same directory as for the personal preferences file is
used.

Note: Whenever Wireshark is closed, your recent file
will be overwritten with the new settings, destroying any comments and
unknown/obsolete settings that were in the file.
--
// end::gui[]

Disabled (Enabled) Protocols::
+
--
The __disabled_protos__ files contain system-wide and personal lists of
protocols that have been disabled, so that their dissectors are never
called.  The files contain protocol names, one per line, where the
protocol name is the same name that would be used in a display filter
for the protocol:

  http
  tcp     # a comment

If a protocol is listed in the global __disabled_protos__ file it cannot
be enabled by the user.
// tag::gui[]
Thus it is not displayed in the __Analyze::Enabled Protocols__ dialog box.
// end::gui[]

The global __disabled_protos__ file uses the same directory as the global
preferences file.

The personal __disabled_protos__ file uses the same directory as the
personal preferences file.

The __disabled_protos__ files list only protocols that are enabled by default
but have been disabled; protocols that are disabled by default (such as some
postdissectors) are not listed. There are analogous __enabled_protos__ files
for protocols that are disabled by default but have been enabled.

// tag::gui[]
Note: Whenever the disabled protocols list is saved by using the __Save__
button in the __Analyze:Enabled Protocols__ dialog box, your personal
disabled protocols file will be overwritten with the new settings,
destroying any comments that were in the file.
// end::gui[]
--

Heuristic Dissectors::
+
--
The __heuristic_protos__ files contain system-wide and personal lists of
heuristic dissectors and indicate whether they are enabled or disabled.
The files contain heuristic dissector unique short names, one per line,
followed by a comma and 0 for disabled and 1 for enabled:

  quic,1
  rtcp_stun,1
  rtcp_udp,1
  rtp_stun,0
  rtp_udp,0
  tls_tcp,1

The global __heuristic_protos__ file uses the same directory as the global
preferences file.

The personal __heuristic_protos__ file uses the same directory as the
personal preferences file.

// The global heuristic_protos doesn't have the "set_cant_toggle"
// features that the enabled_protos and disabled_protos files do.
--

Name Resolution (hosts)::
+
--
Entries in __hosts__ files in the global and personal preferences
directory are used to resolve IPv4 and IPv6 addresses before any
other attempts are made to resolve them.
The file has the standard __hosts__ file syntax; each line contains one
IP address and name, separated by whitespace. The personal __hosts__
file, if present, overrides the one in the global directory.

Capture filter name resolution is handled by libpcap on UNIX-compatible
systems, such as Linux, macOS, \*BSD, Solaris, and AIX, and Npcap or
WinPcap on Windows.  As such the Wireshark personal __hosts__ file will
not be consulted for capture filter name resolution.
--


Name Resolution (subnets)::
+
--
If an IPv4 address cannot be translated via name resolution (no exact
match is found) then a partial match is attempted via the __subnets__ file.
Both the global __subnets__ file and personal __subnets__ files are used
if they exist.

Each line of this file 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".
--

Name Resolution (ethers)::
+
--
The __ethers__ files are consulted to correlate 6-byte hardware addresses to
names.  First the personal __ethers__ file is tried and if an address is not
found there the global __ethers__ file is tried next.

Each line contains one hardware address and name, separated by
whitespace.  The digits of the hardware address are separated by colons
(:), dashes (-) or periods (.).  The same separator character must be
used consistently in an address.  The following three lines are valid
lines of an __ethers__ file:

  ff:ff:ff:ff:ff:ff          Broadcast
  c0-00-ff-ff-ff-ff          TR_broadcast
  00.00.00.00.00.00          Zero_broadcast

The global __ethers__ file is looked for in the __/etc__ directory on
UNIX-compatible systems, such as Linux, macOS, \*BSD, Solaris, and AIX,
and in the main installation directory (for example, __C:\Program
Files\Wireshark__) on Windows systems.

The personal __ethers__ file is looked for in the same directory as the personal
preferences file.

Capture filter name resolution is handled by libpcap on UNIX-compatible
systems and Npcap or WinPcap on Windows.  As such the Wireshark personal
__ethers__ file will not be consulted for capture filter name
resolution.
--

Name Resolution (manuf)::
+
--
The __manuf__ file is used to match the 3-byte vendor portion of a 6-byte
hardware address with the manufacturer's name; it can also contain well-known
MAC addresses and address ranges specified with a netmask.  The format of the
file is similar the __ethers__ files, except that entries such as:

  00:00:0C      Cisco     Cisco Systems, Inc

can be provided, with the 3-byte OUI and both an abbreviated and long name for
a vendor, and entries such as:

  00-00-0C-07-AC/40     All-HSRP-routers

can be specified, with a MAC address and a mask indicating how many bits
of the address must match.  The above entry, for example, has 40
significant bits, or 5 bytes, and would match addresses from
00-00-0C-07-AC-00 through 00-00-0C-07-AC-FF.  The mask need not be a
multiple of 8.

A global __manuf__ file is looked for in the same directory as the global
preferences file, and a personal __manuf__ file is looked for in the same
directory as the personal preferences file.

In earlier versions of Wireshark, official information from the IEEE
Registration Authority was distributed in this format as the global
__manuf__ file. This information is now compiled in to speed program
startup, but the internal information can be written out in this format
with *tshark -G manuf*.

In addition to the __manuf__ file, another file with the same format,
__wka__, is looked for in the global directory. This file is distributed
with Wireshark, and contains data about well-known MAC adddresses and
address ranges assembled from various non IEEE but respected sources.
--

Name Resolution (services)::
+
--
The __services__ file is used to translate port numbers into names.
Both the global __services__ file and personal __services__ files are used
if they exist.

The file has the standard __services__ file syntax; each line contains one
(service) name and one transport identifier separated by white space.  The
transport identifier includes one port number and one transport protocol name
(typically tcp, udp, or sctp) separated by a /.

An example is:

mydns       5045/udp     # My own Domain Name Server
mydns       5045/tcp     # My own Domain Name Server

In earlier versions of Wireshark, official information from the IANA
Registry was distributed in this format as the global __services__ file.
This information is now compiled in to speed program startup, but the
internal information can be written out in this format with *tshark -G services*.
--

Name Resolution (ipxnets)::
+
--
The __ipxnets__ files are used to correlate 4-byte IPX network numbers to
names.  First the global __ipxnets__ file is tried and if that address is not
found there the personal one is tried next.

The format is the same as the __ethers__
file, except that each address is four bytes instead of six.
Additionally, the address can be represented as a single hexadecimal
number, as is more common in the IPX world, rather than four hex octets.
For example, these four lines are valid lines of an __ipxnets__ file:

  C0.A8.2C.00              HR
  c0-a8-1c-00              CEO
  00:00:BE:EF              IT_Server1
  110f                     FileServer3

The global __ipxnets__ file is looked for in the __/etc__ directory on
UNIX-compatible systems, such as Linux, macOS, \*BSD, Solaris, and AIX,
and in the main installation directory (for example, __C:\Program
Files\Wireshark__) on Windows systems.

The personal __ipxnets__ file is looked for in the same directory as the
personal preferences file.
--

Name Resolution (ss7pcs)::
+
--
The __ss7pcs__ file is used to translate SS7 point codes to names.
It is read from the personal configuration directory.

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.
An example is:

  2-1234 MyPointCode1

--

Name Resolution (vlans)::
+
--
The __vlans__ file is used to translate VLAN tag IDs into names.
It is read from the personal configuration directory.

Each line in this file consists of one VLAN tag ID separated by whitespace
from a name.  An example is:

  123    Server-Lan
  2049   HR-Client-LAN

--

// tag::gui[]
Capture Filters::
+
--
The __cfilters__ files contain system-wide and personal capture filters.
Each line contains one filter, starting with the string displayed in the
dialog box in quotation marks, followed by the filter string itself:

  "HTTP" port 80
  "DCERPC" port 135

The global __cfilters__ file uses the same directory as the
global preferences file.

The personal __cfilters__ file uses the same directory as the personal
preferences file.  It is written through the Capture:Capture Filters
dialog.

If the global __cfilters__ file exists, it is used only if the personal
__cfilters__ file does not exist; global and personal capture filters are
not merged.
--

Display Filters::
+
--
The __dfilters__ files contain system-wide and personal display filters.
Each line contains one filter, starting with the string displayed in the
dialog box in quotation marks, followed by the filter string itself:

  "HTTP" http
  "DCERPC" dcerpc

The global __dfilters__ file uses the same directory as the
global preferences file.

The personal __dfilters__ file uses the same directory as the
personal preferences file.  It is written through the Analyze:Display
Filters dialog.

If the global __dfilters__ file exists, it is used only if the personal
__dfilters__ file does not exist; global and personal display filters are
not merged.
--

Display Filter Macros::
+
--
The __dmacros__ files contain system-wide and personal display filter macros.
Each line contains one filter, starting with the string displayed in the
dialog box in quotation marks, followed by the macro expression itself:

  "private_ipv6" ipv6 && $1 == fc00::/7
  "private_ethernet" $1[0] & 0x0F == 2
  "private_ipv4" $1 == 192.168.0.0/16 or $1 == 172.16.0.0/12 or $1 == 10.0.0.0/8

The global __dmacros__ file uses the same directory as the
global preferences file.

The personal __dmacros__ file uses the same directory as the
personal preferences file.  It is written through the Analyze:Display
Filter Macros dialog.

If the global __dmacros__ file exists, it is used only if the personal
__dmacros__ file does not exist; global and personal display filters are
not merged.

Prior to Wireshark 4.4, a __dfilter_macros__ file with a somewhat different
syntax was used. That file is looked for at startup if a __dmacros__ file is
not found and used to migrate to the new format.
--
// end::gui[]

Color Filters (Coloring Rules)::
+
--
The __colorfilters__ files contain system-wide and personal color filters.
Each line contains one filter, starting with the string displayed in the
dialog box, followed by the corresponding display filter.  Then the
background and foreground colors are appended:

  # a comment
  @tcp@tcp@[59345,58980,65534][0,0,0]
  @udp@udp@[28834,57427,65533][0,0,0]

The global __colorfilters__ file uses the same directory as the
global preferences file.

The personal __colorfilters__ file uses the same directory as the
personal preferences file.  It is written through the View:Coloring Rules
dialog.

If the global __colorfilters__ file exists, it is used only if the personal
__colorfilters__ file does not exist; global and personal color filters are
not merged.
--

Plugins::
+
--
Wireshark looks for plugins in both a personal plugin folder and a
global plugin folder.

On UNIX-compatible systems, such as Linux, macOS, \*BSD, Solaris, and
AIX, the global plugin directory is __lib/wireshark/plugins/__ (on
some systems substitute __lib64__ for __lib__) under the main installation
directory (for example, __/usr/local/lib/wireshark/plugins/__). The personal
plugin directory is __$HOME/.local/lib/wireshark/plugins__.

On macOS, if Wireshark is installed as an application bundle, the global plugin
folder is instead __%APPDIR%/Contents/PlugIns/wireshark__.

On Windows, the global plugin folder is __plugins/__ under the main
installation directory (for example, __C:\Program Files\Wireshark\plugins\__).
The personal plugin folder is __%APPDATA%\Wireshark\plugins__ (or, if
%APPDATA% isn't defined, __%USERPROFILE%\Application Data\Wireshark\plugins__).

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).  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_).

NOTE: On UNIX-compatible systems, Lua plugins (but not binary plugins) may also
be placed in __$XDG_CONFIG_HOME/wireshark/plugins__,
(or, if __$XDG_CONFIG_HOME/wireshark__ does not exist while __$HOME/.wireshark__
does exist, __$HOME/.wireshark/plugins__.)

Note that a dissector plugin module may support more than one protocol;
there is not necessarily a one-to-one correspondence between dissector plugin
modules and protocols.  Protocols supported by a dissector plugin module are
enabled and disabled in the same way as protocols built into Wireshark.
--