docbook/wsug_src/WSUG_app_files.xml

   1 <!-- WSUG Appendix Files -->
   2 <!-- $Id$ -->
   3
   4 <appendix id="AppFiles">
   5   <title>Files and Folders</title>
   6
   7   <section id="ChAppFilesCaptureFilesSection"><title>Capture Files</title>
   8     <para>
   9         To understand which information will remain available after
  10         the captured packets are saved to a capture file,
  11         it's helpful to know a bit about the capture file contents.
  12     </para>
  13     <para>
  14         Wireshark uses the libpcap file format as the default format to save
  15         captured packets; this format has existed for a long time and it's pretty simple.
  16         However, it has some drawbacks: it's not extensible and lacks some
  17         information that would be really helpful (e.g. being able to add a comment
  18         to a packet such as "the problems start here" would be really nice).
  19     </para>
  20     <para>
  21         In addition to the libpcap format, Wireshark supports several different
  22         capture file formats. However, the problems described above also applies
  23         for these formats.
  24     </para>
  25     <para>
  26         A new capture file format "PCAP Next Generation Dump File Format"
  27         is currently under development, which will fix these drawbacks.
  28         However, it still might take a while until the new file format is ready
  29         and Wireshark can use it.
  30     </para>
  31   <section id="ChIOFileContentSection"><title>Libpcap File Contents</title>
  32     <para>
  33         At the start of each libpcap capture file some basic information is stored
  34         like a magic number to identify the libpcap file format.
  35         The most interesting information of this file start is the link layer type
  36         (Ethernet, Token Ring, ...).
  37     </para>
  38     <para>
  39         The following data is saved for each packet:
  40         <itemizedlist>
  41         <listitem>
  42           <para>
  43             the timestamp with millisecond resolution
  44           </para>
  45         </listitem>
  46         <listitem>
  47           <para>
  48             the packet length as it was "on the wire"
  49           </para>
  50         </listitem>
  51         <listitem>
  52           <para>
  53                 the packet length as it's saved in the file
  54           </para>
  55         </listitem>
  56         <listitem>
  57           <para>
  58             the packet's raw bytes
  59           </para>
  60         </listitem>
  61       </itemizedlist>
  62         A detailed description of the libpcap file format can be found at:
  63         <ulink url="http://wiki.wireshark.org/Development/LibpcapFileFormat"/>
  64     </para>
  65   </section>
  66   <section id="ChIOFileNotContentSection"><title>Not Saved in the Capture File</title>
  67     <para>
  68         Probably even more interesting for everyday Wireshark usage is to know
  69         the things that are <command>not saved</command> in the capture file:
  70         <itemizedlist>
  71         <listitem>
  72           <para>
  73             current selections (selected packet, ...)
  74           </para>
  75         </listitem>
  76         <listitem>
  77           <para>
  78             name resolution information, see <xref
  79                 linkend="ChAdvNameResolutionSection"/> for details
  80                 <warning><title>Warning!</title>
  81                 <para>
  82                 The name resolution information is rebuilt each time Wireshark is
  83                 restarted so this information might even change when the capture file
  84                 is reopened on the same machine later!
  85                 </para>
  86                 </warning>
  87           </para>
  88         </listitem>
  89         <listitem>
  90           <para>
  91             the number of packets dropped while capturing
  92           </para>
  93         </listitem>
  94         <listitem>
  95           <para>
  96             packet marks set with "Edit/Mark Packet"
  97           </para>
  98         </listitem>
  99         <listitem>
 100           <para>
 101             time references set with "Edit/Time Reference"
 102           </para>
 103         </listitem>
 104         <listitem>
 105           <para>
 106             the current display filter
 107           </para>
 108         </listitem>
 109         <listitem>
 110           <para>
 111             ...
 112           </para>
 113         </listitem>
 114       </itemizedlist>
 115     </para>
 116   </section>
 117   </section>
 118
 119     <section id="ChAppFilesConfigurationSection"><title>Configuration Files and Folders</title>
 120     <para>
 121       Wireshark uses a number of files and folders while it is running. Some
 122           of these reside in the personal configuration folder and are used to
 123           maintain information between runs of Wireshark, while some of them are
 124           maintained in system areas.
 125     </para>
 126         <tip><title>Tip</title>
 127         <para>A list of the folders Wireshark actually uses can be found under the
 128         <command>Folders</command> tab in the dialog box shown when you select
 129         <command>About Wireshark</command> from the <command>Help</command> menu.
 130         </para>
 131         </tip>
 132     <para>
 133         The content format of the configuration files is the same on all platforms.
 134         However, to match the different policies for Unix and Windows platforms,
 135         different folders are used for these files.
 136     </para>
 137     <table id="AppFilesTabFolders" frame="none">
 138         <title>Configuration files and folders overview</title>
 139       <tgroup cols="4">
 140         <colspec colnum="1" colwidth="72pt"/>
 141           <colspec colnum="2" colwidth="80pt"/>
 142           <colspec colnum="3" colwidth="80pt"/>
 143             <thead>
 144               <row>
 145                 <entry>File/Folder</entry>
 146                 <entry>Description</entry>
 147                 <entry>Unix/Linux folders</entry>
 148                 <entry>Windows folders</entry>
 149               </row>
 150             </thead>
 151             <tbody>
 152               <row>
 153                 <entry><command>preferences</command></entry>
 154                 <entry>Settings from the Preferences dialog box.</entry>
 155                 <entry>/etc/wireshark.conf, $HOME/.wireshark/preferences</entry>
 156                 <entry>%WIRESHARK%\wireshark.conf, %APPDATA%\Wireshark\preferences</entry>
 157               </row>
 158               <row>
 159                 <entry><command>recent</command></entry>
 160                 <entry>Recent GUI settings (e.g. recent files lists).</entry>
 161                 <entry>$HOME/.wireshark/recent</entry>
 162                 <entry>%APPDATA%\Wireshark\recent</entry>
 163               </row>
 164               <row>
 165                 <entry><command>cfilters</command></entry>
 166                 <entry>Capture filters.</entry>
 167                 <entry>$HOME/.wireshark/cfilters</entry>
 168                 <entry>%WIRESHARK%\cfilters, %APPDATA%\Wireshark\cfilters</entry>
 169               </row>
 170               <row>
 171                 <entry><command>dfilters</command></entry>
 172                 <entry>Display filters.</entry>
 173                 <entry>$HOME/.wireshark/dfilters</entry>
 174                 <entry>%WIRESHARK%\dfilters, %APPDATA%\Wireshark\dfilters</entry>
 175               </row>
 176               <row>
 177                 <entry><command>colorfilters</command></entry>
 178                 <entry>Coloring rules.</entry>
 179                 <entry>$HOME/.wireshark/colorfilters</entry>
 180                 <entry>%WIRESHARK%\colorfilters, %APPDATA%\Wireshark\colorfilters</entry>
 181               </row>
 182               <row>
 183                 <entry><command>disabled_protos</command></entry>
 184                 <entry>Disabled protocols.</entry>
 185                 <entry>$HOME/.wireshark/disabled_protos</entry>
 186                 <entry>%WIRESHARK%\disabled_protos, %APPDATA%\Wireshark\disabled_protos</entry>
 187               </row>
 188               <row>
 189                 <entry><command>ethers</command></entry>
 190                 <entry>Ethernet name resolution.</entry>
 191                 <entry>/etc/ethers, $HOME/.wireshark/ethers</entry>
 192                 <entry>%WIRESHARK%\ethers, %APPDATA%\Wireshark\ethers</entry>
 193               </row>
 194               <row>
 195                 <entry><command>manuf</command></entry>
 196                 <entry>Ethernet name resolution.</entry>
 197                 <entry>/etc/manuf, $HOME/.wireshark/manuf</entry>
 198                 <entry>%WIRESHARK%\manuf, %APPDATA%\Wireshark\manuf</entry>
 199               </row>
 200               <row>
 201                 <entry><command>hosts</command></entry>
 202                 <entry>IPv4 and IPv6 name resolution.</entry>
 203                 <entry>/etc/hosts, $HOME/.wireshark/hosts</entry>
 204                 <entry>%WIRESHARK%\hosts, %APPDATA%\Wireshark\hosts</entry>
 205               </row>
 206               <row>
 207                 <entry><command>ipxnets</command></entry>
 208                 <entry>IPX name resolution.</entry>
 209                 <entry>/etc/ipxnets, $HOME/.wireshark/ipxnets</entry>
 210                 <entry>%WIRESHARK%\ipxnets, %APPDATA%\Wireshark\ipxnets</entry>
 211               </row>
 212               <row>
 213                 <entry><command>plugins</command></entry>
 214                 <entry>Plugin directories.</entry>
 215                 <entry>/usr/share/wireshark/plugins,
 216               /usr/local/share/wireshark/plugins,
 217               $HOME/.wireshark/plugins
 218                 </entry>
 219                 <entry>%WIRESHARK%\plugins\&lt;version&gt;,
 220                 %APPDATA%\Wireshark\plugins</entry>
 221               </row>
 222               <row>
 223                 <entry><command>temp</command></entry>
 224                 <entry>Temporary files.</entry>
 225                 <entry>Environment: TMPDIR</entry>
 226                 <entry>Environment: TMPDIR or TEMP</entry>
 227               </row>
 228             </tbody>
 229       </tgroup>
 230     </table>
 231         <note><title>Windows folders</title>
 232         <para>
 233         %APPDATA% points to the personal configuration folder, e.g.:
 234         <filename>C:\Documents and Settings\&lt;username&gt;\Application Data</filename>
 235         (details can be found at: <xref linkend="ChWindowsProfiles"/>),
 236         </para>
 237         <para>
 238         %WIRESHARK% points to the Wireshark program folder, e.g.:
 239         <filename>C:\Program Files\Wireshark</filename>
 240         </para>
 241         </note>
 242         <note><title>Unix/Linux folders</title>
 243         <para>
 244         The <filename>/etc</filename> folder is the global Wireshark configuration
 245         folder. The folder actually used on your system
 246         may vary, maybe something like: <filename>/usr/local/etc</filename>.
 247         </para>
 248         <para>
 249     $HOME is usually something like: <filename>/home/&lt;username&gt;</filename>
 250         </para>
 251         </note>
 252     <para>
 253       <variablelist>
 254         <varlistentry>
 255           <term><command>preferences/wireshark.conf</command></term>
 256           <listitem>
 257             <para>
 258               This file contains your Wireshark preferences,
 259               including defaults for capturing and displaying packets.
 260               It is a simple text file containing statements of the form:
 261               <programlisting>
 262 variable: value
 263                   </programlisting>
 264               The settings from this file are
 265                   read in at program start and written to disk when you press the
 266                   Save button in the "Preferences" dialog box.
 267             </para>
 268           </listitem>
 269         </varlistentry>
 270         <varlistentry>
 271           <term><command>recent</command></term>
 272           <listitem>
 273             <para>
 274               This file contains various GUI related settings like the main window
 275                   position and size, the recent files list and such.
 276               It is a simple text file containing statements of the form:
 277               <programlisting>
 278 variable: value
 279                   </programlisting>
 280                   It is read at program start and written at program exit.
 281             </para>
 282           </listitem>
 283         </varlistentry>
 284         <varlistentry><term><command>cfilters</command></term>
 285           <listitem>
 286             <para>
 287               This file contains all the capture filters that you have defined
 288               and saved. It consists of one or more lines, where each
 289               line has the following format:
 290               <programlisting>
 291 "&lt;filter name>" &lt;filter string>
 292               </programlisting>
 293                 The settings from this file are read in at program start and written
 294                 to disk when you press the Save button in the "Capture Filters" dialog
 295                 box.
 296                 </para>
 297           </listitem>
 298         </varlistentry>
 299         <varlistentry><term><command>dfilters</command></term>
 300           <listitem>
 301             <para>
 302               This file contains all the display filters that you have defined
 303               and saved. It consists of one or more lines, where each
 304               line has the following format:
 305               <programlisting>
 306 "&lt;filter name>" &lt;filter string>
 307               </programlisting>
 308                 The settings from this file are read in at program start and written
 309                 to disk when you press the Save button in the "Display Filters" dialog
 310                 box.
 311             </para>
 312           </listitem>
 313         </varlistentry>
 314         <varlistentry>
 315           <term><command>colorfilters</command></term>
 316           <listitem>
 317             <para>
 318               This file contains all the color filters that you have
 319               defined and saved. It consists of one or more lines,
 320               where each line has the following format:
 321               <programlisting>
 322 @&lt;filter name>@&lt;filter string>
 323 @[&lt;bg RGB(16-bit)>][&lt;fg RGB(16-bit)>]
 324               </programlisting>
 325             </para>
 326                 <para>
 327                 The settings from this file are read in at program start and written
 328                 to disk when you press the Save button in the "Coloring Rules" dialog
 329                 box.
 330                 </para>
 331           </listitem>
 332         </varlistentry>
 333         <varlistentry>
 334           <term><command>disabled_protos</command></term>
 335           <listitem>
 336             <para>
 337               Each line in this file specifies a disabled protocol name. The
 338                   following are some examples:
 339               <programlisting>
 340 tcp
 341 udp
 342                   </programlisting>
 343             </para>
 344                 <para>
 345                 The settings from this file are read in at program start and written
 346                 to disk when you press the Save button in the "Enabled Protocols"
 347                 dialog box.
 348                 </para>
 349           </listitem>
 350         </varlistentry>
 351         <varlistentry>
 352           <term>
 353             <command>ethers</command>
 354           </term>
 355           <listitem>
 356             <para>
 357               When Wireshark is trying to translate Ethernet hardware
 358               addresses to names, it consults the files listed in
 359                   <xref linkend="AppFilesTabFolders"/>.
 360               If an address is not found in /etc/ethers,
 361               Wireshark looks in $HOME/.wireshark/ethers
 362             </para>
 363             <para>
 364               Each line in these files consists of one hardware address and
 365               name separated by whitespace. The digits of hardware
 366               addresses are separated by colons (:), dashes (-) or
 367               periods(.). The following are some examples:
 368               <programlisting>
 369 ff-ff-ff-ff-ff-ff    Broadcast
 370 c0-00-ff-ff-ff-ff    TR_broadcast
 371 00.2b.08.93.4b.a1    Freds_machine
 372               </programlisting>
 373                 The settings from this file are read in at program start and never
 374                 written by Wireshark.
 375             </para>
 376           </listitem>
 377         </varlistentry>
 378         <varlistentry>
 379           <term><command>manuf</command></term>
 380           <listitem>
 381             <para>
 382               Wireshark uses the files listed in <xref linkend="AppFilesTabFolders"/>
 383                   to translate the first three bytes of an Ethernet address into a
 384                   manufacturers name.  This file has the same format as the ethers
 385                   file, except addresses are three bytes long.
 386             </para>
 387             <para>
 388               An example is:
 389               <programlisting>
 390 00:00:01        Xerox                  # XEROX CORPORATION
 391               </programlisting>
 392             </para>
 393                 <para>
 394                 The settings from this file are read in at program start and never
 395                 written by Wireshark.
 396                 </para>
 397           </listitem>
 398         </varlistentry>
 399         <varlistentry>
 400           <term><command>hosts</command></term>
 401           <listitem>
 402             <para>
 403               Wireshark uses the files listed in <xref linkend="AppFilesTabFolders"/>
 404                   to translate IPv4 and IPv6 addresses into names.
 405             </para>
 406             <para>
 407                   This file has the same format as the usual /etc/hosts file on Unix systems.
 408             </para>
 409             <para>
 410               An example is:
 411               <programlisting>
 412 # Comments must be prepended by the # sign!
 413 192.168.0.1 homeserver
 414               </programlisting>
 415             </para>
 416                 <para>
 417                 The settings from this file are read in at program start and never
 418                 written by Wireshark.
 419                 </para>
 420           </listitem>
 421         </varlistentry>
 422         <varlistentry>
 423           <term><command>ipxnets</command></term>
 424           <listitem>
 425             <para>
 426               Wireshark uses the files listed in <xref linkend="AppFilesTabFolders"/>
 427                   to translate IPX network numbers into names.
 428             </para>
 429             <para>
 430               An example is:
 431               <programlisting>
 432 C0.A8.2C.00      HR
 433 c0-a8-1c-00      CEO
 434 00:00:BE:EF      IT_Server1
 435 110f             FileServer3
 436               </programlisting>
 437             </para>
 438                 <para>
 439                 The settings from this file are read in at program start and never
 440                 written by Wireshark.
 441                 </para>
 442           </listitem>
 443         </varlistentry>
 444         <varlistentry>
 445           <term><command>plugins</command> folder</term>
 446           <listitem>
 447             <para>
 448               Wireshark searches for plugins in the directories listed in
 449                   <xref linkend="AppFilesTabFolders"/>.
 450               They are searched in the order listed.
 451             </para>
 452           </listitem>
 453         </varlistentry>
 454         <varlistentry>
 455           <term><command>temp</command> folder</term>
 456           <listitem>
 457             <para>
 458               If you start a new capture and don't specify a filename for it,
 459                   Wireshark uses this directory to store that file; see
 460                   <xref linkend="ChCapCaptureFiles"/>.
 461             </para>
 462           </listitem>
 463         </varlistentry>
 464       </variablelist>
 465     </para>
 466         </section>
 467
 468         <section id="ChWindowsFolder"><title>Windows folders</title>
 469         <para>
 470         Here you will find some details about the folders used in Wireshark
 471         on different Windows versions.
 472         </para>
 473         <para>
 474         As already mentioned, you can find the currently used folders in the
 475         <command>About Wireshark</command> dialog.
 476         </para>
 477
 478         <section id="ChWindowsProfiles"><title>Windows profiles</title>
 479         <para>
 480         Windows uses some special directories to store user configuration files
 481         which define the "user profile". This can be confusing, as the default directory location
 482         changed from Windows version to version and might also be different for English
 483         and internationalized versions of Windows.
 484         </para>
 485         <note><title>Note!</title>
 486         <para>
 487         If you've upgraded to a new Windows version, your profile might
 488         be kept in the former location, so the defaults mentioned here might not
 489         apply.
 490         </para>
 491         </note>
 492         <para>
 493         The following guides
 494         you to the right place where to look for Wireshark's profile data.
 495         </para>
 496         <para>
 497       <variablelist>
 498         <varlistentry>
 499           <term><command>Vista</command></term>
 500           <listitem>
 501         <para>
 502         <filename>C:\Users\&lt;username&gt;\AppData\Roaming\Wireshark</filename>
 503         </para>
 504           </listitem>
 505         </varlistentry>
 506         <varlistentry>
 507           <term><command>XP/2000</command></term>
 508           <listitem>
 509         <para>
 510         <filename>C:\Documents and Settings\&lt;username&gt;\Application Data</filename>,
 511         "Documents and Settings" and "Application Data" might be internationalized.
 512         </para>
 513           </listitem>
 514         </varlistentry>
 515         <varlistentry>
 516           <term><command>NT 4 (no longer supported by Wireshark)</command></term>
 517           <listitem>
 518         <para>
 519         <filename>C:\WINNT\Profiles\&lt;username&gt;\Application Data\Wireshark</filename>
 520         </para>
 521           </listitem>
 522         </varlistentry>
 523         <varlistentry>
 524           <term><command>ME/98 - with enabled user profiles  (no longer supported by Wireshark)</command></term>
 525           <listitem>
 526         <para>
 527         In Windows ME and 98 you can enable separate user profiles. In that case,
 528         something like:
 529         <filename>C:\windows\Profiles\&lt;username&gt;\Application Data\Wireshark</filename>
 530         is used.
 531         </para>
 532           </listitem>
 533         </varlistentry>
 534         <varlistentry>
 535           <term><command>ME/98/95 (no longer supported by Wireshark)</command></term>
 536           <listitem>
 537         <para>
 538         The default in Windows ME/98/95 is: all users work with the same profile,
 539         which is located at:
 540         <filename>C:\windows\Application Data\Wireshark</filename>
 541         </para>
 542           </listitem>
 543         </varlistentry>
 544       </variablelist>
 545         </para>
 546         </section>
 547
 548         <section id="ChWindowsRoamingProfiles">
 549         <title>Windows Vista/XP/2000/NT roaming profiles</title>
 550         <para>
 551         The following will only be applicable if you are using roaming profiles.
 552         This might be the case, if you work in a Windows domain environment
 553         (used in company networks). The configurations of all
 554         programs you use won't be saved on the local hard drive of the computer
 555         you are currently working on, but on the domain server.
 556         </para>
 557         <para>
 558         As Wireshark is using the correct places to store its profile data,
 559         your settings will travel with you, if you logon to a different computer
 560         the next time.
 561         </para>
 562         <para>
 563         There is an exception to this: The "Local Settings" folder in your profile
 564         data (typically something like:
 565         <filename>C:\Documents and Settings\&lt;username&gt;\Local Settings</filename>)
 566         will not be transferred to the domain server. This is the default for
 567         temporary capture files.
 568         </para>
 569         </section>
 570
 571         <section id="ChWindowsTempFolder">
 572         <title>Windows temporary folder</title>
 573         <para>
 574         Wireshark uses the folder which is set by the TMPDIR or TEMP environment
 575         variable. This variable will be set by the Windows installer.
 576         </para>
 577         <para>
 578       <variablelist>
 579         <varlistentry>
 580           <term><command>Vista</command></term>
 581           <listitem>
 582         <para>
 583         <filename>XXX - could someone give information about this?</filename>
 584         </para>
 585           </listitem>
 586         </varlistentry>
 587         <varlistentry>
 588           <term><command>XP/2000</command></term>
 589           <listitem>
 590         <para>
 591         <filename>C:\Documents and Settings\&lt;username&gt;\Local Settings\Temp</filename>
 592         </para>
 593           </listitem>
 594         </varlistentry>
 595         <varlistentry>
 596           <term><command>NT 4</command></term>
 597           <listitem>
 598         <para>
 599         <filename>C:\TEMP</filename>
 600         </para>
 601           </listitem>
 602         </varlistentry>
 603       </variablelist>
 604         </para>
 605         </section>
 606
 607         </section>
 608
 609 </appendix>
 610 <!-- End of WSUG Appendix Files -->