diff options
Diffstat (limited to 'doc/man_pages/files.adoc')
| -rw-r--r-- | doc/man_pages/files.adoc | 458 |
1 files changed, 458 insertions, 0 deletions
diff --git a/doc/man_pages/files.adoc b/doc/man_pages/files.adoc new file mode 100644 index 00000000..9653ff27 --- /dev/null +++ b/doc/man_pages/files.adoc @@ -0,0 +1,458 @@ +== 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. +-- |