diff options
Diffstat (limited to '')
| -rw-r--r-- | docbook/wsug_src/wsug_files.adoc | 647 |
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 |