docbook/wsug_src/WSUG_chapter_customize.xml

   1 <!-- WSUG Chapter Customizing -->
   2 <!-- $Id$ -->
   3
   4 <chapter id="ChapterCustomize">
   5   <title>Customizing Wireshark</title>
   6
   7   <section id="ChCustIntroduction"><title>Introduction</title>
   8     <para>
   9         Wireshark's default behaviour will usually suit your needs pretty well.
  10         However, as you become more familiar with Wireshark, it can be customized
  11         in various ways to suit your needs even better. In this chapter we explore:
  12         <itemizedlist>
  13         <listitem>
  14           <para>
  15             How to start Wireshark with command line parameters
  16           </para>
  17         </listitem>
  18         <listitem>
  19           <para>
  20             How to colorize the packet list
  21           </para>
  22         </listitem>
  23         <listitem>
  24           <para>
  25             How to control protocol dissection
  26           </para>
  27         </listitem>
  28         <listitem>
  29           <para>
  30             How to use the various preference settings
  31           </para>
  32         </listitem>
  33         </itemizedlist>
  34         </para>
  35   </section>
  36
  37   <section id="ChCustCommandLine"><title>Start Wireshark from the command line</title>
  38     <para>
  39       You can start <application>Wireshark</application> from the command
  40       line, but it can also be started from most Window managers
  41       as well. In this section we will look at starting it from the command
  42       line.
  43     </para>
  44     <para>
  45       <application>Wireshark</application> supports a large number of
  46       command line parameters. To see what they are, simply enter the
  47       command <command>wireshark -h</command> and the help information
  48       shown in <xref linkend="ChCustEx1"/> (or something similar) should be
  49           printed.
  50         <example id="ChCustEx1">
  51           <title>Help information available from Wireshark</title>
  52           <programlisting>
  53 Wireshark 0.99.6
  54 Interactively dump and analyze network traffic.
  55 See http://www.wireshark.org for more information.
  56
  57 Copyright 1998-2007 Gerald Combs &lt;gerald@wireshark.org> and contributors.
  58 This is free software; see the source for copying conditions. There is NO
  59 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  60
  61 Usage: wireshark [options] ... [ &lt;infile> ]
  62
  63 Capture interface:
  64   -i &lt;interface>           name or idx of interface (def: first non-loopback)
  65   -f &lt;capture filter>      packet filter in libpcap filter syntax
  66   -s &lt;snaplen>             packet snapshot length (def: 65535)
  67   -p                       don't capture in promiscuous mode
  68   -k                       start capturing immediately (def: do nothing)
  69   -Q                       quit Wireshark after capturing
  70   -S                       update packet display when new packets are captured
  71   -l                       turn on automatic scrolling while -S is in use
  72   -B &lt;buffer size>         size of kernel buffer (def: 1MB)
  73   -y &lt;link type>           link layer type (def: first appropriate)
  74   -D                       print list of interfaces and exit
  75   -L                       print list of link-layer types of iface and exit
  76
  77 Capture stop conditions:
  78   -c &lt;packet count>        stop after n packets (def: infinite)
  79   -a &lt;autostop cond.> ...  duration:NUM - stop after NUM seconds
  80                            filesize:NUM - stop this file after NUM KB
  81                               files:NUM - stop after NUM files
  82 Capture output:
  83   -b &lt;ringbuffer opt.> ... duration:NUM - switch to next file after NUM secs
  84                            filesize:NUM - switch to next file after NUM KB
  85                               files:NUM - ringbuffer: replace after NUM files
  86 Input file:
  87   -r &lt;infile>              set the filename to read from (no pipes or stdin!)
  88
  89 Processing:
  90   -R &lt;read filter>         packet filter in Wireshark display filter syntax
  91   -n                       disable all name resolutions (def: all enabled)
  92   -N &lt;name resolve flags>  enable specific name resolution(s): "mntC"
  93
  94 User interface:
  95   -g &lt;packet number>       go to specified packet number after "-r"
  96   -m &lt;font>                set the font name used for most text
  97   -t ad|a|r|d|dd|e         output format of time stamps (def: r: rel. to first)
  98   -X &lt;key>:&lt;value>         eXtension options, see man page for details
  99   -z &lt;statistics>          show various statistics, see man page for details
 100
 101 Output:
 102   -w &lt;outfile|->           set the output filename (or '-' for stdout)
 103
 104 Miscellaneous:
 105   -h                       display this help and exit
 106   -v                       display version info and exit
 107   -P &lt;key:path>            persconf:path - personal configuration files
 108                            persdata:path - personal data files
 109   -o &lt;name>:&lt;value> ...    override preference or recent setting
 110
 111 </programlisting>
 112         </example>
 113
 114         We will examine each of the command line options in turn.
 115     </para>
 116     <para>
 117       The first thing to notice is that issuing the command
 118       <command>wireshark</command> by itself will bring up
 119       <application>Wireshark</application>.
 120       However, you can include as many of the command line parameters as
 121       you like. Their meanings are as follows ( in alphabetical order ):
 122           XXX - is the alphabetical order a good choice? Maybe better task based?
 123       <variablelist>
 124           <varlistentry><term><command>-a &lt;capture autostop condition></command></term>
 125           <listitem>
 126                 <para>
 127         Specify a criterion that specifies when Wireshark is to stop writing
 128                 to a capture file. The criterion is of the form test:value, where test
 129                 is one of:
 130                 <variablelist>
 131                 <varlistentry><term><command>duration</command>:value</term>
 132                         <listitem><para>
 133                         Stop writing to a capture file after value of seconds have elapsed.
 134                         </para></listitem>
 135                 </varlistentry>
 136                 <varlistentry><term><command>filesize</command>:value</term>
 137                         <listitem><para>
 138                         Stop writing to a capture file after it reaches a size of value
 139                         kilobytes (where a kilobyte is 1000 bytes, not 1024 bytes). If
 140                         this option is used together with the -b option, Wireshark will
 141                         stop writing to the current capture file and switch to the next
 142                         one if filesize is reached.
 143                         </para></listitem>
 144                 </varlistentry>
 145                 <varlistentry><term><command>files</command>:value</term>
 146                         <listitem><para>
 147                         Stop writing to capture files after value number of files were
 148                         written.
 149                         </para></listitem>
 150                 </varlistentry>
 151                 </variablelist>
 152                 </para>
 153           </listitem>
 154         </varlistentry>
 155         <varlistentry><term><command>-b &lt;capture ring buffer option></command></term>
 156           <listitem>
 157             <para>
 158                 If a maximum capture file size was specified, this option causes Wireshark to run
 159                 in "ring buffer" mode, with the specified number of files. In "ring
 160                 buffer" mode, Wireshark will write to several capture files. Their
 161                 name is based on the number of the file and on the creation date and
 162                 time.
 163             </para>
 164             <para>
 165                 When the first capture file fills up, Wireshark will switch to writing
 166                 to the next file, until it fills up the last file, at which point
 167                 it'll discard the data in the first file (unless 0 is specified, in
 168                 which case, the number of files is unlimited) and start writing to
 169                 that file and so on.
 170             </para>
 171             <para>
 172                 If the optional duration is specified, Wireshark will also switch to
 173                 the next file when the specified number of seconds has elapsed even
 174                 if the current file is not completely fills up.
 175             </para>
 176             <para>
 177                 <variablelist>
 178                 <varlistentry><term><command>duration</command>:value</term>
 179                         <listitem><para>
 180                         Switch to the next file after value seconds have elapsed, even
 181                         if the current file is not completely filled up.
 182                         </para></listitem>
 183                 </varlistentry>
 184                 <varlistentry><term><command>filesize</command>:value</term>
 185                         <listitem><para>
 186                         Switch to the next file after it reaches a size of value kilobytes
 187                         (where a kilobyte is 1000 bytes, not 1024 bytes).
 188                         </para></listitem>
 189                 </varlistentry>
 190                 <varlistentry><term><command>files</command>:value</term>
 191                         <listitem><para>
 192                         Begin again with the first file after value number of files were
 193                         written (form a ring buffer).
 194                         </para></listitem>
 195                 </varlistentry>
 196                 </variablelist>
 197             </para>
 198           </listitem>
 199         </varlistentry>
 200         <varlistentry><term><command>-B &lt;capture buffer size (Win32 only)></command></term>
 201           <listitem>
 202             <para>
 203               Win32 only: set capture buffer size (in MB, default is 1MB). This
 204                   is used by the the capture driver to buffer packet data until that
 205                   data can be written to disk. If you encounter packet drops while
 206                   capturing, try to increase this size.
 207             </para>
 208           </listitem>
 209         </varlistentry>
 210         <varlistentry><term><command>-c &lt;capture packet count></command></term>
 211           <listitem>
 212             <para>
 213               This option specifies the maximum number of packets to capture
 214               when capturing live data.  It would be used in conjunction
 215               with the <command>-k</command> option.
 216             </para>
 217           </listitem>
 218         </varlistentry>
 219         <varlistentry><term><command>-D</command></term>
 220           <listitem>
 221             <para>
 222 Print a list of the interfaces on which Wireshark can capture, and
 223 exit.  For each network interface, a number and an
 224 interface name, possibly followed by a text description of the
 225 interface, is printed.  The interface name or the number can be supplied
 226 to the <command>-i</command> flag to specify an interface on which to capture.
 227             </para>
 228             <para>
 229 This can be useful on systems that don't have a command to list them
 230 (e.g., Windows systems, or UNIX systems lacking <command>ifconfig -a</command>);
 231 the number can be useful on Windows 2000 and later systems, where the
 232 interface name is a somewhat complex string.
 233             </para>
 234             <para>
 235 Note that "can capture" means that Wireshark was able to open
 236 that device to do a live capture; if, on your system, a program doing a
 237 network capture must be run from an account with special privileges (for
 238 example, as root), then, if Wireshark is run with the <command>-D</command> flag and
 239 is not run from such an account, it will not list any interfaces.
 240             </para>
 241           </listitem>
 242         </varlistentry>
 243         <varlistentry><term><command>-f &lt;capture filter></command></term>
 244           <listitem>
 245             <para>
 246               This option sets the initial capture filter expression to
 247               be used when capturing packets.
 248             </para>
 249           </listitem>
 250         </varlistentry>
 251         <varlistentry><term><command>-g &lt;packet number></command></term>
 252           <listitem>
 253             <para>
 254               After reading in a capture file using the -r flag, go to the given
 255                   packet number.
 256             </para>
 257           </listitem>
 258         </varlistentry>
 259         <varlistentry><term><command>-h</command></term>
 260           <listitem>
 261             <para>
 262               The <command>-h</command> option requests Wireshark to print
 263               its version and usage instructions (as shown above) and exit.
 264             </para>
 265           </listitem>
 266         </varlistentry>
 267         <varlistentry><term><command>-i &lt;capture interface></command></term>
 268           <listitem>
 269             <para>
 270 Set the name of the network interface or pipe to use for live packet
 271 capture.
 272             </para>
 273             <para>
 274 Network interface names should match one of the names listed in
 275 <command>wireshark -D</command> (described above); a number, as reported by
 276 <command>wireshark -D</command>, can also be used.  If you're using UNIX, <command>netstat
 277 -i</command> or <command>ifconfig -a</command> might also work to list interface names,
 278 although not all versions of UNIX support the <command>-a</command> flag to <command>ifconfig</command>.
 279             </para>
 280             <para>
 281 If no interface is specified, Wireshark searches the list of
 282 interfaces, choosing the first non-loopback interface if there are any
 283 non-loopback interfaces, and choosing the first loopback interface if
 284 there are no non-loopback interfaces; if there are no interfaces,
 285 Wireshark reports an error and doesn't start the capture.
 286             </para>
 287             <para>
 288 Pipe names should be either the name of a FIFO (named pipe) or ``-'' to
 289 read data from the standard input.  Data read from pipes must be in
 290 standard libpcap format.
 291             </para>
 292           </listitem>
 293         </varlistentry>
 294         <varlistentry><term><command>-k</command></term>
 295           <listitem>
 296             <para>
 297               The <command>-k</command> option specifies that Wireshark
 298               should start capturing packets immediately.  This option
 299               requires the use of the <command>-i</command> parameter to
 300               specify the interface that packet capture will occur from.
 301             </para>
 302           </listitem>
 303         </varlistentry>
 304         <varlistentry><term><command>-l</command></term>
 305           <listitem>
 306             <para>
 307               This option turns on automatic scrolling if the packet
 308               list pane is being updated automatically as packets arrive
 309               during a capture ( as specified by the <command>-S</command>
 310               flag).
 311             </para>
 312           </listitem>
 313         </varlistentry>
 314         <varlistentry><term><command>-L</command></term>
 315           <listitem>
 316             <para>
 317                   List the data link types supported by the interface and exit.
 318             </para>
 319           </listitem>
 320         </varlistentry>
 321         <varlistentry><term><command>-m &lt;font></command></term>
 322           <listitem>
 323             <para>
 324               This option sets the name of the font used for most text
 325               displayed by Wireshark. XXX - add an example!
 326             </para>
 327           </listitem>
 328         </varlistentry>
 329         <varlistentry><term><command>-n</command></term>
 330           <listitem>
 331             <para>
 332                 Disable network object name resolution (such as hostname, TCP and UDP
 333                 port names).
 334                 </para>
 335           </listitem>
 336         </varlistentry>
 337         <varlistentry><term><command>-N &lt;name resolving flags></command></term>
 338           <listitem>
 339             <para>
 340               Turns on name resolving for particular types of addresses
 341               and port numbers; the argument is a string that may contain
 342               the letters <command>m</command> to enable MAC address
 343               resolution, <command>n</command> to enable network address
 344               resolution, and <command>t</command> to enable transport-layer
 345               port number resolution.  This overrides <command>-n</command>
 346               if both <command>-N</command> and <command>-n</command> are
 347               present. The letter C enables concurrent (asynchronous) DNS lookups.
 348             </para>
 349           </listitem>
 350         </varlistentry>
 351         <varlistentry>
 352           <term><command>-o &lt;preference/recent settings&gt;</command></term>
 353           <listitem>
 354             <para>
 355               Sets a preference or recent value, overriding the default value and
 356               any value read from a preference/recent file.  The argument to the
 357               flag is a string of the form prefname:value, where prefname
 358               is the name of the preference (which is the same name that
 359               would appear in the preference/recent file), and value is the value
 360               to which it should be set.  Multiple instances of
 361               <command>-o &lt;preference settings&gt; </command> can be
 362               given on a single command line.
 363             </para>
 364             <para>An example of setting a single preference would be: </para>
 365             <para>
 366               <command>
 367                 wireshark -o mgcp.display_dissect_tree:TRUE
 368               </command>
 369             </para>
 370             <para>
 371               An example of setting multiple preferences would be:
 372             </para>
 373             <para>
 374               <command>
 375                 wireshark -o mgcp.display_dissect_tree:TRUE -o mgcp.udp.callagent_port:2627
 376               </command>
 377             </para>
 378                 <tip><title>Tip!</title>
 379                 <para>
 380                 You can get a list of all available preference strings from the
 381                 preferences file, see <xref linkend="AppFiles"/>.
 382                 </para>
 383                 </tip>
 384           </listitem>
 385         </varlistentry>
 386         <varlistentry><term><command>-p</command></term>
 387           <listitem>
 388             <para>
 389               Don't put the interface into promiscuous mode.  Note that
 390               the interface might be in promiscuous mode for some other
 391               reason; hence, -p cannot be used to ensure that the only
 392               traffic that is captured is traffic sent to or from the
 393               machine on which Wireshark is running, broadcast traffic, and
 394               multicast traffic to addresses received by that machine.
 395             </para>
 396           </listitem>
 397         </varlistentry>
 398         <varlistentry><term><command>-P &lt;path setting></command></term>
 399           <listitem>
 400                 <para>
 401                 Special path settings usually detected automatically. This is used
 402                 for special cases, e.g. starting Wireshark from a known location on
 403                 an USB stick.
 404                 </para>
 405                 <para>
 406                 The criterion is of the form key:path, where key is one of:
 407                 <variablelist>
 408                 <varlistentry><term><command>persconf</command>:path</term>
 409                         <listitem><para>
 410                         path of personal configuration files, like the preferences files.
 411                         </para></listitem>
 412                 </varlistentry>
 413                 <varlistentry><term><command>persdata</command>:path</term>
 414                         <listitem><para>
 415                         path of personal data files, it's the folder initially opened.
 416                         After the initilization, the recent file will keep the folder
 417                         last used.
 418                         </para></listitem>
 419                 </varlistentry>
 420                 </variablelist>
 421                 </para>
 422           </listitem>
 423         </varlistentry>
 424         <varlistentry><term><command>-Q</command></term>
 425           <listitem>
 426             <para>
 427               This option forces Wireshark to exit when capturing is
 428               complete. It can be used with the <command>-c</command> option.
 429               It must be used in conjunction with the
 430               <command>-i</command> and <command>-w</command> options.
 431             </para>
 432           </listitem>
 433         </varlistentry>
 434         <varlistentry><term><command>-r &lt;infile></command></term>
 435           <listitem>
 436             <para>
 437               This option provides the name of a capture file for Wireshark
 438               to read and display. This capture file can be in one of the
 439               formats Wireshark understands.
 440             </para>
 441           </listitem>
 442         </varlistentry>
 443         <varlistentry><term><command>-R &lt;read (display) filter></command></term>
 444           <listitem>
 445             <para>
 446               This option specifies a display filter to be applied when
 447               reading packets from a capture file. The syntax of this
 448               filter is that of the display filters discussed in
 449               <xref linkend="ChWorkDisplayFilterSection"/>.  Packets not
 450                   matching the filter are discarded.
 451             </para>
 452           </listitem>
 453         </varlistentry>
 454         <varlistentry><term><command>-s &lt;capture snaplen></command></term>
 455           <listitem>
 456             <para>
 457               This option specifies the snapshot length to use when
 458               capturing packets. Wireshark will only capture
 459               <command>&lt;snaplen></command> bytes of data for each packet.
 460             </para>
 461           </listitem>
 462         </varlistentry>
 463         <varlistentry><term><command>-S</command></term>
 464           <listitem>
 465             <para>
 466               This option specifies that Wireshark will display packets as
 467               it captures them. This is done by capturing in one process
 468               and displaying them in a separate process. This is the same
 469                   as "Update list of packets in real time" in the Capture Options
 470                   dialog box.
 471             </para>
 472           </listitem>
 473         </varlistentry>
 474         <varlistentry>
 475           <term><command>-t &lt;time stamp format></command></term>
 476           <listitem>
 477             <para>
 478               This option sets the format of packet timestamps that are
 479               displayed in the packet list window.  The format can be one of:
 480               <itemizedlist>
 481                 <listitem>
 482                   <para>
 483                     <command>r</command> relative, which specifies timestamps are
 484                     displayed relative to the first packet captured.
 485                   </para>
 486                 </listitem>
 487                 <listitem>
 488                   <para>
 489                     <command>a</command> absolute, which specifies that actual times
 490                         be displayed for all packets.
 491                   </para>
 492                 </listitem>
 493                 <listitem>
 494                   <para>
 495                     <command>ad</command> absolute with date, which specifies that
 496                         actual dates and times be displayed for all packets.
 497                   </para>
 498                 </listitem>
 499                 <listitem>
 500                   <para>
 501                     <command>d</command> delta, which specifies that timestamps
 502                     are relative to the previous packet.
 503                   </para>
 504                 </listitem>
 505                 <listitem>
 506                   <para>
 507                     <command>e</command> epoch, which specifies that timestamps
 508                     are seconds since epoch (Jan 1, 1970 00:00:00)
 509                   </para>
 510                 </listitem>
 511               </itemizedlist>
 512             </para>
 513           </listitem>
 514         </varlistentry>
 515         <varlistentry><term><command>-v</command></term>
 516           <listitem>
 517             <para>
 518               The <command>-v</command> option requests
 519               Wireshark to print out its version information and exit.
 520             </para>
 521           </listitem>
 522         </varlistentry>
 523         <varlistentry><term><command>-w &lt;savefile></command></term>
 524           <listitem>
 525             <para>
 526               This option sets the name of the <command>savefile</command>
 527               to be used when saving a capture file.
 528             </para>
 529           </listitem>
 530         </varlistentry>
 531         <varlistentry><term><command>-y &lt;capture link type></command></term>
 532           <listitem>
 533             <para>
 534                 If a capture is started from the command line with -k, set the data
 535                 link type to use while capturing packets. The values reported by -L
 536                 are the values that can be used.
 537                 </para>
 538           </listitem>
 539         </varlistentry>
 540         <varlistentry><term><command>-X &lt;eXtension option></command></term>
 541           <listitem>
 542             <para>
 543         Specify an option to be passed to a TShark module. The eXtension
 544         option is in the form extension_key:value, where extension_key can
 545         be:
 546         </para>
 547         <para>
 548         <command>lua_script</command>:lua_script_filename; Tells Wireshark to load the given script in addition to the default Lua scripts.
 549         </para>
 550           </listitem>
 551         </varlistentry>
 552         <varlistentry><term><command>-z &lt;statistics-string></command></term>
 553           <listitem>
 554             <para>
 555                 Get Wireshark to collect various types of statistics and display the
 556                 result in a window that updates in semi-real time.
 557                 XXX - add more details here!
 558                 </para>
 559           </listitem>
 560         </varlistentry>
 561       </variablelist>
 562     </para>
 563   </section>
 564
 565   <section id="ChCustColorizationSection"><title>Packet colorization</title>
 566     <para>
 567       A very useful mechanism available in Wireshark is packet colorization.
 568       You can set-up Wireshark so that it will colorize packets according to a
 569       filter. This allows you to emphasize the packets you are usually
 570           interested in.
 571     </para>
 572     <tip>
 573       <title>Tip!</title>
 574       <para>
 575           You will find a lot of Coloring Rule examples at the <command>Wireshark
 576           Wiki Coloring Rules page</command> at <ulink
 577           url="&WiresharkWikiColoringRulesPage;">&WiresharkWikiColoringRulesPage;</ulink>.
 578       </para>
 579     </tip>
 580     <para>
 581       To colorize packets, select the <command>Coloring Rules...</command> menu item from
 582       the <command>View</command> menu; Wireshark will pop up the "Coloring Rules"
 583       dialog box as shown in <xref linkend="ChCustColoringRulesDialog"/>.
 584     </para>
 585     <figure id="ChCustColoringRulesDialog">
 586       <title>The "Coloring Rules" dialog box</title>
 587       <graphic entityref="WiresharkColoringRulesDialog" format="PNG"/>
 588     </figure>
 589     <para>
 590       Once the Coloring Rules dialog box is up, there are a number
 591       of buttons you can use, depending on whether or not you have any
 592       color filters installed already.
 593     </para>
 594     <note><title>Note!</title>
 595         <para>
 596           You will need to carefully select the order the coloring rules are listed
 597           as they are applied in order from top to bottom.
 598           So, more specific rules need to be listed before more general rules.
 599           For example, if you have a color rule for UDP before the one for DNS,
 600           the color rule for DNS will never be applied (as DNS uses UDP, so the
 601           UDP rule will match first).
 602         </para>
 603     </note>
 604     <para>
 605           If this is the first time you have used Coloring Rules, click on the New
 606           button which will bring up the Edit color filter dialog box as shown in
 607       <xref linkend="ChCustEditColorDialog"/>.
 608     </para>
 609     <figure id="ChCustEditColorDialog">
 610       <title>The "Edit Color Filter" dialog box</title>
 611       <graphic entityref="WiresharkEditColorDialog" format="PNG"/>
 612     </figure>
 613     <para>
 614       In the Edit Color dialog box, simply enter a name for the color filter,
 615       and enter a filter string in the Filter text field.
 616       <xref linkend="ChCustEditColorDialog"/> shows the values
 617         <command>arp</command> and <command>arp</command> which means that
 618         the name of the color filter is <command>arp</command> and the filter
 619         will select protocols of type <command>arp</command>.  Once you have
 620         entered these values, you can choose a foreground and background
 621         color for packets that match the filter expression.  Click on
 622         <command>Foreground color...</command> or
 623         <command>Background color...</command> to achieve this and
 624         Wireshark will pop up the Choose foreground/background color for
 625         protocol dialog box as shown in
 626         <xref linkend="ChCustChooseColorDialog"/>.
 627     </para>
 628     <figure id="ChCustChooseColorDialog">
 629       <title>The "Choose color" dialog box</title>
 630       <graphic entityref="WiresharkChooseColorDialog" format="PNG"/>
 631     </figure>
 632     <para>
 633       Select the color you desire for the selected packets and click on OK.
 634     </para>
 635     <note>
 636       <title>Note!</title>
 637       <para>
 638         You must select a color in the colorbar next to the colorwheel to
 639         load values into the RGB values. Alternatively, you can set the
 640         values to select the color you want.
 641       </para>
 642     </note>
 643     <para>
 644       <xref linkend="ChCustColorFilterMany"/> shows an example of several color
 645         filters being used in Wireshark. You may not like the color choices,
 646         however, feel free to choose your own.
 647     </para>
 648     <para>
 649         If you are uncertain which coloring rule actually took place for a
 650         specific packet, have a look at the [Coloring Rule Name: ...] and
 651         [Coloring Rule String: ...] fields.
 652     </para>
 653     <figure id="ChCustColorFilterMany">
 654       <title>Using color filters with Wireshark</title>
 655       <graphic entityref="WiresharkColoringFields" format="PNG"/>
 656     </figure>
 657   </section>
 658
 659   <section id="ChCustProtocolDissectionSection">
 660         <title>Control Protocol dissection</title>
 661         <para>
 662                 The user can control how protocols are dissected.
 663         </para>
 664         <para>
 665                 Each protocol has its own dissector, so dissecting a complete packet will
 666                 typically involve several dissectors. As Wireshark tries to find the
 667                 right dissector for each packet (using static "routes" and heuristics
 668                 "guessing"), it might choose the wrong dissector in your specific
 669                 case. For example, Wireshark won't know if you use a common protocol
 670                 on an uncommon TCP port, e.g. using HTTP on TCP port 800 instead of
 671                 the standard port 80.
 672         </para>
 673         <para>
 674                 There are two ways to control the relations between protocol
 675                 dissectors: disable a protocol dissector completely or temporarily
 676                 divert the way Wireshark calls the dissectors.
 677         </para>
 678         <section id="ChAdvEnabledProtocols"><title>The "Enabled Protocols" dialog
 679         box</title>
 680         <para>
 681                 The Enabled Protocols dialog box lets you enable or
 682                 disable specific protocols; all protocols are enabled by default.
 683                 When a protocol is disabled, Wireshark stops processing a packet
 684                 whenever that protocol is encountered.
 685         </para>
 686         <note><title>Note!</title>
 687                 <para>
 688                 Disabling a protocol will prevent information about higher-layer
 689                 protocols from being displayed.  For example,
 690                 suppose you disabled the IP protocol and selected
 691                 a packet containing Ethernet, IP, TCP, and HTTP
 692                 information.  The Ethernet information would be
 693                 displayed, but the IP, TCP and HTTP information
 694                 would not - disabling IP would prevent it and
 695                 the other protocols from being displayed.
 696                 </para>
 697         </note>
 698         <para>
 699           To enable/disable protocols select the <command>Enabled Protocols...</command>
 700           item from the <command>Analyze</command> menu; Wireshark will pop up the "Enabled Protocols"
 701           dialog box as shown in <xref linkend="ChAdvEnabledProtocolsFig"/>.
 702         </para>
 703     <figure id="ChAdvEnabledProtocolsFig">
 704       <title>The "Enabled Protocols" dialog box</title>
 705       <graphic entityref="WiresharkEnabledProtocols" format="PNG"/>
 706     </figure>
 707         <para>
 708                 To disable or enable a protocol, simply click on it using the
 709                 mouse or press the space bar when the protocol is highlighted.
 710                 Note that typing the first few letters
 711                 of the protocol name when the Enabled Protocols dialog box is active
 712                 will temporarily open a search text box and
 713                 automatically select the first matching protocol name (if it exists).
 714         </para>
 715         <warning><title>Warning!</title>
 716                 <para>
 717                 You have to use the Save button to save your settings. The OK or Apply
 718                 buttons will not save your changes permanently, so they will be lost
 719                 when Wireshark is closed.
 720                 </para>
 721         </warning>
 722     <para>
 723       You can choose from the following actions:
 724       <orderedlist>
 725         <listitem>
 726           <para>
 727             <command>Enable All</command>: Enable all protocols in the list.
 728           </para>
 729         </listitem>
 730         <listitem>
 731           <para>
 732             <command>Disable All</command>: Disable all protocols in the list.
 733           </para>
 734         </listitem>
 735         <listitem>
 736           <para>
 737             <command>Invert</command>: Toggle the state of all protocols in the
 738                 list.
 739           </para>
 740         </listitem>
 741         <listitem>
 742           <para>
 743             <command>OK</command>: Apply the changes and close the dialog box.
 744           </para>
 745         </listitem>
 746         <listitem>
 747           <para>
 748             <command>Apply</command>: Apply the changes and keep the dialog box
 749                 open.
 750           </para>
 751         </listitem>
 752         <listitem>
 753           <para>
 754             <command>Save</command>: Save the settings to the disabled_protos, see
 755                 <xref linkend="AppFiles"/> for details.
 756           </para>
 757         </listitem>
 758         <listitem>
 759           <para>
 760             <command>Cancel</command>: Cancel the changes and close the dialog box.
 761           </para>
 762         </listitem>
 763       </orderedlist>
 764     </para>
 765         </section>
 766
 767     <section id="ChAdvDecodeAs"><title>User Specified Decodes</title>
 768         <para>
 769                 The "Decode As" functionality let you temporarily divert specific
 770                 protocol dissections. This might be useful for example, if you do some
 771                 uncommon experiments on your network.
 772         </para>
 773         <para>
 774           Decode As is accessed by selecting the <command>Decode As...</command> item from
 775           the <command>Analyze</command> menu; Wireshark will pop up the "Decode As"
 776           dialog box as shown in <xref linkend="ChAdvDecodeAsFig"/>.
 777         </para>
 778     <para>
 779     <figure id="ChAdvDecodeAsFig">
 780       <title>The "Decode As" dialog box</title>
 781       <graphic scale="100" entityref="WiresharkDecodeAs" format="PNG"/>
 782     </figure>
 783         The content of this dialog box depends on the selected packet when it
 784         was opened.
 785         <warning><title>Warning!</title>
 786                 <para>
 787                 The user specified decodes can not be saved. If you quit Wireshark,
 788                 these settings will be lost.
 789                 </para>
 790         </warning>
 791       <orderedlist>
 792         <listitem>
 793           <para>
 794             <command>Decode</command>: Decode packets the selected way.
 795           </para>
 796         </listitem>
 797         <listitem>
 798           <para>
 799             <command>Do not decode</command>: Do not decode packets the selected
 800                 way.
 801           </para>
 802         </listitem>
 803         <listitem>
 804           <para>
 805             <command>Link/Network/Transport</command>: Specify the network layer
 806                 at which "Decode As" should take place. Which of these pages are
 807                 available depends on the content of the selected packet when this
 808                 dialog box is opened.
 809           </para>
 810         </listitem>
 811         <listitem>
 812           <para>
 813             <command>Show Current</command>: Open a dialog box showing the
 814                 current list of user specified decodes.
 815           </para>
 816         </listitem>
 817         <listitem>
 818           <para>
 819             <command>OK</command>: Apply the currently selected decode and close
 820                 the dialog box.
 821           </para>
 822         </listitem>
 823         <listitem>
 824           <para>
 825             <command>Apply</command>: Apply the currently selected decode and keep
 826                 the dialog box open.
 827           </para>
 828         </listitem>
 829         <listitem>
 830           <para>
 831             <command>Cancel</command>: Cancel the changes and close the dialog box.
 832           </para>
 833         </listitem>
 834       </orderedlist>
 835         </para>
 836         </section>
 837
 838     <section id="ChAdvDecodeAsShow"><title>Show User Specified Decodes</title>
 839     <para>
 840         This dialog box shows the currently active user specified decodes.
 841     <figure id="ChAdvDecodeAsShowFig">
 842       <title>The "Decode As: Show" dialog box</title>
 843       <graphic entityref="WiresharkDecodeAsShow" format="PNG"/>
 844     </figure>
 845       <orderedlist>
 846         <listitem>
 847           <para>
 848             <command>OK</command>: Close this dialog box.
 849           </para>
 850         </listitem>
 851         <listitem>
 852           <para>
 853             <command>Clear</command>: Removes all user specified decodes.
 854           </para>
 855         </listitem>
 856       </orderedlist>
 857         </para>
 858   </section>
 859   </section>
 860
 861   <section id="ChCustPreferencesSection"><title>Preferences</title>
 862     <para>
 863       There are a number of preferences you can set. Simply
 864       select the <command>Preferences...</command> menu item from
 865       the <command>Edit</command> menu; and Wireshark
 866       will pop up the Preferences dialog box as shown in
 867       <xref linkend="ChCustGUIPrefPage"/>, with the "User Interface" page as
 868           default. On the left side is a tree where you can select the page to be
 869           shown.
 870           <note><title>Note!</title>
 871           <para>
 872           Preference settings are added frequently. For a recent explanation of
 873           the preference pages and their settings have a look at the
 874           <command>Wireshark Wiki Preferences page</command> at <ulink
 875           url="&WiresharkWikiPreferencesPage;">&WiresharkWikiPreferencesPage;</ulink>.
 876       </para>
 877       </note>
 878           <warning>
 879                 <title>Warning!</title>
 880                 <para>
 881                 The OK or Apply button will not save the preference settings,
 882                 you'll have to save the settings by clicking the Save button.
 883                 </para>
 884           </warning>
 885         <itemizedlist>
 886                 <listitem>
 887                   <para>
 888                         The <command>OK</command> button will apply the preferences
 889                         settings and close the dialog.
 890                   </para>
 891                 </listitem>
 892                 <listitem>
 893                   <para>
 894                         The <command>Apply</command> button will apply the preferences
 895                         settings and keep the dialog open.
 896                   </para>
 897                 </listitem>
 898                 <listitem>
 899                   <para>
 900                         The <command>Save</command> button will apply the preferences
 901                         settings, save the settings on the hard disk and keep the dialog open.
 902                   </para>
 903                 </listitem>
 904                 <listitem>
 905                   <para>
 906                         The <command>Cancel</command> button will restore all preferences
 907                         settings to the last saved state.
 908                   </para>
 909                 </listitem>
 910         </itemizedlist>
 911     </para>
 912     <figure id="ChCustGUIPrefPage">
 913       <title>The preferences dialog box</title>
 914       <graphic entityref="WiresharkGUIPreferences" format="PNG"/>
 915     </figure>
 916   </section>
 917   <section id="ChUserTable"><title>User Table</title>
 918     <para>
 919       The User Table editor is used for managing various tables in wireshark. Its main dialog works
 920       very similarly to that of <xref linkend="ChCustColorizationSection"/>.
 921       </para>
 922   </section>
 923
 924
 925   <section id="ChDisplayFilterMacrosSection"><title>Display Filter Macros</title>
 926     <para>
 927         Display Filter Macros are a mechanism to create shortcuts for complex filters. For example defining a
 928         display filter macro named <command>tcp_conv</command> whose text is
 929         <command> ( (ip.src == $1 and ip.dst == $2 and tcp.srcport == $3 and tcp.dstport == $4) or
 930         (ip.src == $2 and ip.dst == $1 and tcp.srcport == $4 and tcp.dstport == $3) ) </command>
 931         would allow to use a display filter like <command>${tcp_conv:10.1.1.2;10.1.1.3;1200;1400}</command>
 932         instead of typing the whole filter.
 933       </para>
 934     <para>
 935         Display Filter Macros can be managed with a <xref linkend="ChUserTable"/> by selecting
 936         the <command>Display Filter Macros</command> menu item from the <command>View</command> Menu.
 937         The User Table has  the following fields
 938       </para>
 939             <variablelist>
 940           <varlistentry><term><command>name</command></term>
 941           <listitem>
 942                 <para>
 943                         The name of the macro.
 944                 </para>
 945           </listitem>
 946           </varlistentry>
 947           <varlistentry><term><command>text</command></term>
 948           <listitem>
 949                 <para>
 950                         The replacement text for the macro it uses $1, $2, $3, ... as the input arguments.
 951                 </para>
 952           </listitem>
 953           </varlistentry>
 954       </variablelist>
 955
 956   </section>
 957
 958
 959     <section id="ChK12ProtocolsSection"><title>Tektronix K12xx/15 RF5 protocols Table</title>
 960     <para>
 961         The Tektronix K12xx/15 rf5 file format uses helper files (*.stk) to identify the various protocols that are
 962         used by a certain interface. Wireshark doesn't read these stk files, it uses a table that helps it identify
 963         which lowest layer protocol to use.
 964    </para>
 965    <para>
 966          Stk file to protocol matching is handled by an <xref linkend="ChUserTable"/> with the following fields.
 967       </para>
 968       <variablelist>
 969           <varlistentry><term><command>match</command></term>
 970           <listitem>
 971                 <para>
 972                    A partial match for an stk filename, the first match wins, so if you have a specific case and a
 973                    general one the specific one must appear first in the list.
 974                 </para>
 975           </listitem>
 976           </varlistentry>
 977           <varlistentry><term><command>protos</command></term>
 978           <listitem>
 979                 <para>
 980                         This is the name of the encapsulating protocol (the lowest layer in the packet data) it can be either
 981                         just the name of the protocol (e.g. mtp2, eth_witoutfcs, sscf-nni ) or the name of the encapsulation
 982                         protocol and the "application" protocol over it separated by a colon (e.g sscop:sscf-nni, sscop:alcap, sscop:nbap, ...)
 983                 </para>
 984           </listitem>
 985           </varlistentry>
 986       </variablelist>
 987   </section>
 988
 989
 990       <section id="ChUserDLTsSection"><title>User DLTs protocol table</title>
 991     <para>
 992           When a pcap file uses one of the user DLTs (147 to 162) wireshark uses this table to know which protocol(s) to use for each user DLT.
 993    </para>
 994    <para>
 995          This table is handled by an <xref linkend="ChUserTable"/> with the following fields.
 996       </para>
 997       <variablelist>
 998           <varlistentry><term><command>encap</command></term>
 999           <listitem>
1000                 <para>
1001                         One of the user dlts.
1002                 </para>
1003           </listitem>
1004           </varlistentry>
1005           <varlistentry><term><command>payload_proto</command></term>
1006           <listitem>
1007                 <para>
1008                         This is the name of the payload protocol (the lowest layer in the packet data). (e.g. "eth" for ethernet, "ip" for IPv4)
1009                 </para>
1010           </listitem>
1011           </varlistentry>
1012           <varlistentry><term><command>header_size</command></term>
1013           <listitem>
1014                 <para>
1015                         If there is a header protocol (before the payload protocol) this tells which size this header is. A value of 0 disables the header protocol.
1016                 </para>
1017           </listitem>
1018           </varlistentry>
1019           <varlistentry><term><command>header_proto</command></term>
1020           <listitem>
1021                 <para>
1022                         The name of the header protocol to be used (uses "data" as default).
1023                 </para>
1024           </listitem>
1025           </varlistentry>
1026                   <varlistentry><term><command>trailer_size</command></term>
1027           <listitem>
1028                 <para>
1029                         If there is a trailer protocol (after the payload protocol) this tells which size this trailer is. A value of 0 disables the trailer protocol.
1030                 </para>
1031           </listitem>
1032           </varlistentry>
1033           <varlistentry><term><command>trailer_proto</command></term>
1034           <listitem>
1035                 <para>
1036                         The name of the trailer protocol to be used (uses "data" as default).
1037                 </para>
1038           </listitem>
1039           </varlistentry>
1040
1041       </variablelist>
1042   </section>
1043
1044
1045
1046       <section id="ChSNMPUsersSection"><title>SNMP users Table</title>
1047     <para>
1048           Wireshark uses this table to verify auhentication and to decrypt encrypted SNMPv3 packets.
1049    </para>
1050    <para>
1051          This table is handled by an <xref linkend="ChUserTable"/> with the following fields.
1052       </para>
1053       <variablelist>
1054           <varlistentry><term><command>engine_id</command></term>
1055           <listitem>
1056                 <para>
1057                         If given this entry will be used only for packets whose engine id is this.
1058                         This field takes an hexadecimal string in the form 0102030405.
1059                 </para>
1060           </listitem>
1061           </varlistentry>
1062           <varlistentry><term><command>userName</command></term>
1063           <listitem>
1064                 <para>
1065                         This is the userName. When a single user has more than one password
1066                         for different SNMP-engines the first entry to match both is taken, if you
1067                         need a catch all engine-id (empty) that entry should be the last one.
1068                 </para>
1069           </listitem>
1070           </varlistentry>
1071           <varlistentry><term><command>auth_model</command></term>
1072           <listitem>
1073                 <para>
1074                         Which auth model to use (either "MD5" or "SHA1").
1075                 </para>
1076           </listitem>
1077           </varlistentry>
1078           <varlistentry><term><command>authPassword</command></term>
1079           <listitem>
1080                 <para>
1081                         The authentication password. Use '\xDD' for unprintable charachters.
1082                         An hexadecimal password must be entered as a sequence of '\xDD' characters.
1083                         For example the hex passowrd 010203040506 must be entered as '\x01\x02\x03\x04\x05\x06'.
1084                 </para>
1085           </listitem>
1086           </varlistentry>
1087                   <varlistentry><term><command>priv_proto</command></term>
1088           <listitem>
1089                 <para>
1090                         Which encryption algorithm to use (either "DES" or "AES").
1091                 </para>
1092           </listitem>
1093           </varlistentry>
1094           <varlistentry><term><command>privPassword</command></term>
1095           <listitem>
1096                 <para>
1097                         The privacy password. Use '\xDD' for unprintable charachters.
1098                         An hexadecimal password must be entered as a sequence of '\xDD' characters.
1099                         For example the hex passowrd 010203040506 must be entered as '\x01\x02\x03\x04\x05\x06'.
1100                 </para>
1101           </listitem>
1102           </varlistentry>
1103
1104       </variablelist>
1105   </section>
1106
1107       <section id="ChSccpUsers"><title>SCCP users Table</title>
1108     <para>
1109           Wireshark uses this table to map specific protocols to a certain DPC/SSN combination for SCCP.
1110    </para>
1111    <para>
1112          This table is handled by an <xref linkend="ChUserTable"/> with the following fields.
1113       </para>
1114       <variablelist>
1115           <varlistentry><term><command>ni</command></term>
1116           <listitem>
1117                 <para>
1118                         An Integer representing the network indicator for which this association is valid.
1119                 </para>
1120           </listitem>
1121           </varlistentry>
1122
1123           <varlistentry><term><command>called_pc</command></term>
1124           <listitem>
1125                 <para>
1126                         An range of integers representing the dpcs for which this association is valid.
1127                 </para>
1128           </listitem>
1129           </varlistentry>
1130
1131           <varlistentry><term><command>called_ssn</command></term>
1132           <listitem>
1133                 <para>
1134                         An range of integers representing the ssns for which this association is valid.
1135                 </para>
1136           </listitem>
1137           </varlistentry>
1138
1139           <varlistentry><term><command>user</command></term>
1140           <listitem>
1141                 <para>
1142                         The protocol that is carried over this association
1143                 </para>
1144           </listitem>
1145           </varlistentry>
1146
1147
1148       </variablelist>
1149   </section>
1150
1151
1152 </chapter>
1153 <!-- End of WSUG Chapter Customizing -->
1154
1155