1// WSUG Appendix Files 2 3[[AppFiles]] 4 5[appendix] 6== Files and Folders 7 8[[ChAppFilesCaptureFilesSection]] 9 10=== Capture Files 11 12To understand which information will remain available after the captured packets 13are saved to a capture file, it’s helpful to know a bit about the capture file 14contents. 15 16Wireshark uses the 17link:https://github.com/pcapng/pcapng[pcapng] file 18format as the default format to save captured packets. It is very flexible 19but other tools may not support it. 20 21Wireshark also supports the 22link:https://gitlab.com/wireshark/wireshark/-/wikis/Development/LibpcapFileFormat[libpcap] file 23format. This is a much simpler format and is well established. However, it has 24some drawbacks: it’s not extensible and lacks some information that would be 25really helpful (e.g. being able to add a comment to a packet such as “the 26problems start here” would be really nice). 27 28In addition to the libpcap format, Wireshark supports several different capture 29file formats. However, the problems described above also applies for these 30formats. 31 32[[ChIOFileContentSection]] 33 34==== Libpcap File Contents 35 36At the start of each libpcap capture file some basic information is stored like 37a magic number to identify the libpcap file format. The most interesting 38information of this file start is the link layer type (Ethernet, 802.11, 39MPLS, etc). 40 41The following data is saved for each packet: 42 43* The timestamp with millisecond resolution 44 45* The packet length as it was “on the wire” 46 47* The packet length as it’s saved in the file 48 49* The packet’s raw bytes 50 51A detailed description of the libpcap file format can be found at 52https://gitlab.com/wireshark/wireshark/-/wikis/Development/LibpcapFileFormat 53 54[[ChIOFileNotContentSection]] 55 56==== Not Saved in the Capture File 57 58You should also know the things that are _not saved_ in capture files: 59 60* Current selections (selected packet, ...) 61 62* Name resolution information. See <<ChAdvNameResolutionSection>> for details 63+ 64-- 65Pcapng files can optionally save name resolution information. Libpcap files 66can’t. Other file formats have varying levels of support. 67-- 68 69* The number of packets dropped while capturing 70 71* Packet marks set with “Edit/Mark Packet” 72 73* Time references set with “Edit/Time Reference” 74 75* The current display filter 76 77[[ChConfigurationPluginFolders]] 78 79=== Configuration File and Plugin Folders 80 81To match the different policies for Unix-like systems and Windows, and 82different policies used on different Unix-like systems, the folders 83containing configuration files and plugins are different on different 84platforms. We indicate the location of the top-level folders under 85which configuration files and plugins are stored here, giving them 86placeholder names independent of their actual location, and use those 87names later when giving the location of the folders for configuration 88files and plugins. 89 90[TIP] 91==== 92A list of the folders Wireshark actually uses can be found under the _Folders_ 93tab in the dialog box shown when you select _About Wireshark_ from the _Help_ 94menu. 95==== 96 97==== Folders on Windows 98 99_%APPDATA%_ is the personal application data folder, e.g.: 100_C:\Users{backslash}**username**\AppData\Roaming\Wireshark_ (details can be 101found at: <<ChWindowsProfiles>>). 102 103_WIRESHARK_ is the Wireshark program folder, e.g.: _C:\Program 104Files\Wireshark_. 105 106==== Folders on Unix-like systems 107 108_$XDG_CONFIG_HOME_ is the folder for user-specific configuration files. 109It’s usually _$HOME/.config_, where _$HOME_ is the user’s home folder, which 110is usually something such as _/home/**username**_, or 111_/Users/**username**_ on macOS. 112 113If you are using macOS and you are running a copy of Wireshark 114installed as an application bundle, _APPDIR_ is the top-level directory 115of the Wireshark application bundle, which will typically be 116_/Applications/Wireshark.app_. Otherwise, _INSTALLDIR_ is the top-level 117directory under which reside the subdirectories in which components of 118Wireshark are installed. This will typically be `/usr` if Wireshark is 119bundled with the system (for example, provided as a package with a Linux 120distribution) and _/usr/local_ if, for example, you’ve build Wireshark 121from source and installed it. 122 123[[ChAppFilesConfigurationSection]] 124 125=== Configuration Files 126 127Wireshark uses a number of configuration files while it is running. Some of these 128reside in the personal configuration folder and are used to maintain information 129between runs of Wireshark, while some of them are maintained in system areas. 130 131The content format of the configuration files is the same on all platforms. 132 133On Windows: 134 135* The personal configuration folder for Wireshark is the 136_Wireshark_ sub-folder of that folder, i.e. _%APPDATA%\Wireshark_. 137 138* The global configuration folder for Wireshark is the Wireshark program 139folder and is also used as the system configuration folder. 140 141On Unix-like systems: 142 143* The personal configuration folder is 144_$XDG_CONFIG_HOME/wireshark_. For backwards compatibility with 145Wireshark before 2.2, if _$XDG_CONFIG_HOME/wireshark_ does not 146exist and _$HOME/.wireshark_ is present, then the latter will be used. 147 148* If you are using macOS and you are running a copy of Wireshark 149installed as an application bundle, the global configuration folder is 150_APPDIR/Contents/Resources/share/wireshark_. Otherwise, the 151global configuration folder is _INSTALLDIR/share/wireshark_. 152 153* The _/etc_ folder is the system configuration folder. The folder 154actually used on your system may vary, maybe something like: 155_/usr/local/etc_. 156 157[[AppFilesTabFolders]] 158.Configuration files overview 159[options="header"] 160|=== 161|File/Folder|Description 162|_cfilters_|Capture filters. 163|_colorfilters_|Coloring rules. 164|__dfilter_buttons__|Display filter buttons. 165|__dfilter_macros__|Display filter macros. 166|_dfilters_|Display filters. 167|__disabled_protos__|Disabled protocols. 168|_ethers_|Ethernet name resolution. 169|_hosts_|IPv4 and IPv6 name resolution. 170|_ipxnets_|IPX name resolution. 171|_manuf_|Ethernet name resolution. 172|_preferences_|Settings from the Preferences dialog box. 173|_recent_|Per-profile GUI settings. 174|__recent_common__|Common GUI settings. 175|_services_|Network services. 176|_ss7pcs_|SS7 point code resolution. 177|_subnets_|IPv4 subnet name resolution. 178|_vlans_|VLAN ID name resolution. 179|=== 180 181[discrete] 182===== File contents 183 184cfilters:: 185+ 186-- 187This file contains all the capture filters that you have defined and saved. It 188consists of one or more lines, where each line has the following format: 189 190---- 191"<filter name>" <filter string> 192---- 193 194At program start, if there is a _cfilters_ file in the personal 195configuration folder, it is read. If there isn’t a _cfilters_ file in 196the personal configuration folder, then, if there is a _cfilters_ file 197in the global configuration folder, it is read. 198 199When you press the Save button in the “Capture Filters” dialog box, 200all the current capture filters are written to the personal capture 201filters file. 202-- 203 204colorfilters:: 205+ 206-- 207This file contains all the color filters that you have defined and saved. It 208consists of one or more lines, where each line has the following format: 209 210---- 211@<filter name>@<filter string>@[<bg RGB(16-bit)>][<fg RGB(16-bit)>] 212---- 213 214At program start, if there is a _colorfilters_ file in the personal 215configuration folder, it is read. If there isn’t a _colorfilters_ file 216in the personal configuration folder, then, if there is a _colorfilters_ 217file in the global configuration folder, it is read. 218 219When you press the Save button in the “Coloring Rules” dialog box, 220all the current color filters are written to the personal color filters 221file. 222-- 223 224dfilter_buttons:: 225+ 226-- 227This file contains all the display filter buttons that you have defined and 228saved. It consists of one or more lines, where each line has the following 229format: 230 231---- 232"TRUE/FALSE","<button label>","<filter string>","<comment string>" 233---- 234 235where the first field is TRUE if the button is enabled (shown). 236 237At program start, if there is a __dfilter_buttons__ file in the personal 238configuration folder, it is read. If there isn’t a __dfilter_buttons__ file 239in the personal configuration folder, then, if there is a __dfilter_buttons__ 240file in the global configuration folder, it is read. 241 242When you save any changes to the filter buttons, all the current display 243filter buttons are written to the personal display filter buttons file. 244-- 245 246dfilter_macros:: 247+ 248-- 249This file contains all the display filter macros that you have defined and saved. 250It consists of one or more lines, where each line has the following format: 251 252---- 253"<macro name>" <filter string> 254---- 255 256At program start, if there is a __dfilter_macros__ file in the personal 257configuration folder, it is read. If there isn’t a __dfilter_macros__ file 258in the personal configuration folder, then, if there is a __dfilter_macros__ 259file in the global configuration folder, it is read. 260 261When you press the Save button in the "Display Filter Macros" dialog box, 262all the current display filter macros are written to the personal display 263filter macros file. 264 265More information about Display Filter Macros is available in 266<<ChDisplayFilterMacrosSection>> 267-- 268 269dfilters:: 270+ 271-- 272This file contains all the display filters that you have defined and saved. It 273consists of one or more lines, where each line has the following format: 274 275---- 276"<filter name>" <filter string> 277---- 278 279At program start, if there is a _dfilters_ file in the personal 280configuration folder, it is read. If there isn’t a _dfilters_ file in 281the personal configuration folder, then, if there is a _dfilters_ file 282in the global configuration folder, it is read. 283 284When you press the Save button in the “Display Filters” dialog box, 285all the current display filters are written to the personal display 286filters file. 287-- 288 289disabled_protos:: 290+ 291-- 292Each line in this file specifies a disabled protocol name. The following are 293some examples: 294 295---- 296tcp 297udp 298---- 299 300At program start, if there is a __disabled_protos__ file in the global 301configuration folder, it is read first. Then, if there is a 302__disabled_protos__ file in the personal configuration folder, that is 303read; if there is an entry for a protocol set in both files, the setting 304in the personal disabled protocols file overrides the setting in the 305global disabled protocols file. 306 307When you press the Save button in the “Enabled Protocols” dialog box, 308the current set of disabled protocols is written to the personal 309disabled protocols file. 310-- 311 312ethers:: 313+ 314-- 315When Wireshark is trying to translate an hardware MAC address to 316a name, it consults the _ethers_ file in the personal configuration 317folder first. If the address is not found in that file, Wireshark 318consults the _ethers_ file in the system configuration folder. 319 320This file has the same format as the _/etc/ethers_ file on some Unix-like systems. 321Each line in these files consists of one hardware address and name separated by 322whitespace. The digits of hardware addresses are separated by colons (:), dashes 323(-) or periods(.). The following are some examples: 324 325---- 326ff-ff-ff-ff-ff-ff Broadcast 327c0-00-ff-ff-ff-ff TR_broadcast 32800.2b.08.93.4b.a1 Freds_machine 329---- 330 331The settings from this file are read in when a MAC address is to be 332translated to a name, and never written by Wireshark. 333-- 334 335hosts:: 336+ 337-- 338Wireshark uses the entries in the _hosts_ files to translate IPv4 and 339IPv6 addresses into names. 340 341At program start, if there is a _hosts_ file in the global configuration 342folder, it is read first. Then, if there is a _hosts_ file in the 343personal configuration folder, that is read; if there is an entry for a 344given IP address in both files, the setting in the personal hosts file 345overrides the entry in the global hosts file. 346 347This file has the same format as the usual _/etc/hosts_ file on Unix systems. 348 349An example is: 350 351---- 352# Comments must be prepended by the # sign! 353192.168.0.1 homeserver 354---- 355 356The settings from this file are read in at program start and never written by 357Wireshark. 358-- 359 360ipxnets:: 361+ 362-- 363When Wireshark is trying to translate an IPX network number to 364a name, it consults the _ipxnets_ file in the personal configuration 365folder first. If the address is not found in that file, Wireshark 366consults the _ipxnets_ file in the system configuration folder. 367 368 369An example is: 370---- 371C0.A8.2C.00 HR 372c0-a8-1c-00 CEO 37300:00:BE:EF IT_Server1 374110f FileServer3 375---- 376 377The settings from this file are read in when an IPX network number is to 378be translated to a name, and never written by Wireshark. 379-- 380 381manuf:: 382+ 383-- 384At program start, if there is a _manuf_ file in the global configuration folder, it is read. 385 386The entries in this file are used to translate MAC address prefixes into short and long manufacturer names. 387Each line consists of a MAC address prefix followed by an abbreviated manufacturer name and the full manufacturer name. 388Prefixes 24 bits long by default and may be followed by an optional length. 389Note that this is not the same format as the _ethers_ file. 390 391Examples are: 392 393---- 39400:00:01 Xerox Xerox Corporation 39500:50:C2:00:30:00/36 Microsof Microsoft 396---- 397 398The settings from this file are read in at program start and never written by Wireshark. 399-- 400 401preferences:: 402+ 403-- 404This file contains your Wireshark preferences, including defaults for capturing 405and displaying packets. It is a simple text file containing statements of the 406form: 407 408---- 409variable: value 410---- 411 412At program start, if there is a _preferences_ file in the global 413configuration folder, it is read first. Then, if there is a 414_preferences_ file in the personal configuration folder, that is read; 415if there is a preference set in both files, the setting in the personal 416preferences file overrides the setting in the global preference file. 417 418If you press the Save button in the “Preferences” dialog box, all the 419current settings are written to the personal preferences file. 420-- 421 422recent:: 423+ 424-- 425This file contains GUI settings that are specific to the current profile, such as column widths and toolbar visibility. 426It is a simple text file containing statements of the form: 427 428---- 429variable: value 430---- 431 432It is read at program start and written when preferences are saved and at program exit. 433It is also written and read whenever you switch to a different profile. 434-- 435 436recent_common:: 437+ 438-- 439This file contains common GUI settings, such as recently opened capture files, recently used filters, and window geometries. 440It is a simple text file containing statements of the form: 441 442---- 443variable: value 444---- 445 446It is read at program start and written when preferences are saved and at program exit. 447-- 448 449services:: 450+ 451-- 452Wireshark uses the _services_ files to translate port numbers into names. 453 454At program start, if there is a _services_ file in the global 455configuration folder, it is read first. Then, if there is a _services_ 456file in the personal configuration folder, that is read; if there is an 457entry for a given port number in both files, the setting in the personal 458hosts file overrides the entry in the global hosts file. 459 460An example is: 461 462---- 463mydns 5045/udp # My own Domain Name Server 464mydns 5045/tcp # My own Domain Name Server 465---- 466 467The settings from these files are read in at program start and never 468written by Wireshark. 469-- 470 471ss7pcs:: 472+ 473-- 474Wireshark uses the _ss7pcs_ file to translate SS7 point codes to node names. 475 476At program start, if there is a _ss7pcs_ file in the personal 477configuration folder, it is read. 478 479Each 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. 480 481An example is: 482---- 4832-1234 MyPointCode1 484---- 485 486The settings from this file are read in at program start and never written by 487Wireshark. 488-- 489 490subnets:: 491+ 492-- 493Wireshark uses the __subnets__ files to translate an IPv4 address into a 494subnet name. If no exact match from a __hosts__ file or from DNS is 495found, Wireshark will attempt a partial match for the subnet of the 496address. 497 498At program start, if there is a _subnets_ file in the personal 499configuration folder, it is read first. Then, if there is a _subnets_ 500file in the global configuration folder, that is read; if there is a 501preference set in both files, the setting in the global preferences file 502overrides the setting in the personal preference file. 503 504Each line in one of these files consists of an IPv4 address, a subnet 505mask length separated only by a “/” and a name separated by whitespace. 506While the address must be a full IPv4 address, any values beyond the 507mask length are subsequently ignored. 508 509An example is: 510---- 511# Comments must be prepended by the # sign! 512192.168.0.0/24 ws_test_network 513---- 514 515A partially matched name will be printed as “subnet-name.remaining-address”. 516For example, “192.168.0.1” under the subnet above would be printed as 517“ws_test_network.1”; if the mask length above had been 16 rather than 24, the 518printed address would be “ws_test_network.0.1”. 519 520The settings from these files are read in at program start and never 521written by Wireshark. 522-- 523 524vlans:: 525+ 526-- 527Wireshark uses the _vlans_ file to translate VLAN tag IDs into names. 528 529If 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. 530 531Each line in this file consists of one VLAN tag ID and a describing name separated by whitespace or tab. 532 533An example is: 534---- 535123 Server-LAN 5362049 HR-Client-LAN 537---- 538 539The settings from this file are read in at program start or when changing 540the active profile and are never written by Wireshark. 541-- 542 543[[ChPluginFolders]] 544 545=== Plugin folders 546 547Wireshark supports plugins for various purposes. Plugins can either be 548scripts written in Lua or code written in C or {cpp} and compiled to 549machine code. 550 551Wireshark looks for plugins in both a personal plugin folder and a 552global plugin folder. Lua plugins are stored in the plugin folders; 553compiled plugins are stored in subfolders of the plugin folders, with 554the subfolder name being the Wireshark minor version number (X.Y). There is 555another hierarchical level for each Wireshark plugin type (libwireshark, 556libwiretap and codecs). So for example the location for a libwireshark plugin 557_foo.so_ (_foo.dll_ on Windows) would be _PLUGINDIR/X.Y/epan_ 558(libwireshark used to be called libepan; the other folder names are _codecs_ 559and _wiretap_). 560 561On Windows: 562 563* The personal plugin folder is _%APPDATA%\Wireshark\plugins_. 564 565* The global plugin folder is _WIRESHARK\plugins_. 566 567On Unix-like systems: 568 569* The personal plugin folder is _~/.local/lib/wireshark/plugins_. 570 571[NOTE] 572==== 573To provide better support for binary plugins this folder changed in Wireshark 2.5. 574It is recommended to use the new folder but *for lua scripts only* you may 575continue to use _$XDG_CONFIG_HOME/wireshark/plugins_ for backward-compatibility. 576This is useful to have older versions of Wireshark installed side-by-side. In case 577of duplicate file names between old and new the new folder wins. 578==== 579 580* If you are running on macOS and Wireshark is installed as an 581application bundle, the global plugin folder is 582_%APPDIR%/Contents/PlugIns/wireshark_, otherwise it’s 583_INSTALLDIR/lib/wireshark/plugins_. 584 585[[ChWindowsFolder]] 586 587=== Windows folders 588 589Here you will find some details about the folders used in Wireshark on different 590Windows versions. 591 592As already mentioned, you can find the currently used folders in the “About 593Wireshark” dialog. 594 595[[ChWindowsProfiles]] 596 597==== Windows profiles 598 599Windows uses some special directories to store user configuration files which 600define the “user profile”. This can be confusing, as the default directory 601location changed from Windows version to version and might also be different for 602English and internationalized versions of Windows. 603 604[NOTE] 605==== 606If you’ve upgraded to a new Windows version, your profile might be kept in the 607former location. The defaults mentioned here might not apply. 608==== 609 610The following guides you to the right place where to look for Wireshark’s 611profile data. 612 613Windows 10, Windows 8.1, Windows 8, Windows 7, Windows Vista, and associated server editions:: 614_C:\Users{backslash}**username**\AppData\Roaming\Wireshark_. 615 616Windows XP and Windows Server 2003 footnote:historical[No longer supported by Wireshark. For historical reference only.]:: 617_C:\Documents and Settings{backslash}**username**\Application Data_. “Documents and 618Settings” and “Application Data” might be internationalized. 619 620[[ChWindowsRoamingProfiles]] 621 622==== Windows roaming profiles 623 624Some larger Windows environments use roaming profiles. If this is the case the 625configurations of all programs you use won’t be saved on your local hard drive. 626They will be stored on the domain server instead. 627 628Your settings will travel with you from computer to computer with one exception. 629The “Local Settings” folder in your profile data (typically something like: 630_C:\Documents and Settings{backslash}**username**\Local Settings_) will not be 631transferred to the domain server. This is the default for temporary capture 632files. 633 634[[ChWindowsTempFolder]] 635 636==== Windows temporary folder 637 638Wireshark uses the folder which is set by the TMPDIR or TEMP environment 639variable. This variable will be set by the Windows installer. 640 641Windows 10, Windows 8.1, Windows 8, Windows 7, Windows Vista, and associated server editions:: 642_C:\Users{backslash}**username**\AppData\Local\Temp_ 643 644Windows XP and Windows Server 2003 footnote:historical[]:: 645_C:\Documents and Settings{backslash}**username**\Local Settings\Temp_ 646 647// End of WSUG Appendix Files 648