docbook/wsug_src/WSUG_chapter_work.xml

   1 <!-- WSUG Chapter Work -->
   2 <!-- $Id$ -->
   3
   4 <chapter id="ChapterWork">
   5   <title>Working with captured packets</title>
   6
   7   <section id="ChWorkViewPacketsSection">
   8     <title>Viewing packets you have captured</title>
   9     <para>
  10       Once you have captured some packets, or you have opened a previously
  11       saved capture file, you can view the packets that are displayed in
  12       the packet list pane by simply clicking on a packet in the
  13       packet list pane, which will bring up the selected packet in the
  14       tree view and byte view panes.
  15     </para>
  16     <para>
  17       You can then expand any part of the tree view by clicking on the
  18       <command>plus</command> sign (the symbol itself may vary) to the left of
  19           that part of the payload,
  20       and you can select individual fields by clicking on them in the tree
  21       view pane. An example with a TCP packet selected is shown in
  22       <xref linkend="ChWorkSelPack1"/>. It also has the Acknowledgment number
  23         in the TCP header selected, which shows up in the byte view as the
  24         selected bytes.
  25         <figure id="ChWorkSelPack1">
  26           <title>Wireshark with a TCP packet selected for viewing</title>
  27           <graphic entityref="WiresharkPacketSelected1" format="PNG"/>
  28         </figure>
  29     </para>
  30     <para>
  31       You can also select and view packets the same way, while Wireshark is
  32           capturing, if you selected "Update list of packets in real time" in the
  33           Wireshark Capture Preferences dialog box.
  34     </para>
  35     <para>
  36       In addition, you can view individual packets in a separate window as
  37       shown in <xref linkend="ChWorkPacketSepView"/>. Do this by selecting the
  38         packet in which you are interested in the packet list pane, and then
  39         select "Show Packet in New Windows" from the Display menu. This
  40         allows you to easily compare two or even more packets.
  41         <figure id="ChWorkPacketSepView">
  42           <title>Viewing a packet in a separate window</title>
  43           <graphic entityref="WiresharkPacketSepView" format="PNG"/>
  44         </figure>
  45     </para>
  46   </section>
  47
  48   <section id="ChWorkDisplayPopUpSection"><title>Pop-up menus</title>
  49     <para>
  50       You can bring up a pop-up menu over either the "Packet List",
  51       "Packet Details" or "Packet Bytes" pane by clicking your right
  52           mouse button at the corresponding pane.
  53     </para>
  54   <section id="ChWorkPacketListPanePopUpMenuSection">
  55     <title>Pop-up menu of the "Packet List" pane</title>
  56     <para>
  57       <figure id="ChWorkPacketListPanePopUpMenu">
  58         <title>Pop-up menu of the "Packet List" pane</title>
  59         <graphic entityref="WiresharkPacketPanePopupMenu" format="PNG"/>
  60       </figure>
  61         </para>
  62           <para>
  63           The following table gives an overview of which functions are available
  64           in this pane, where to find the corresponding function in the main menu,
  65           and a short description of each item.
  66           </para>
  67         <table id="PacketListPopupMenuTable">
  68           <title>The menu items of the "Packet List" pop-up menu</title>
  69           <tgroup cols="3">
  70                 <colspec colnum="1" colwidth="80pt"/>
  71                 <colspec colnum="2" colwidth="80pt"/>
  72             <thead>
  73               <row>
  74                 <entry>Item</entry>
  75                 <entry>Identical to main menu's item:</entry>
  76                 <entry>Description</entry>
  77               </row>
  78             </thead>
  79             <tbody>
  80               <row>
  81                 <entry><command>Mark Packet (toggle)</command></entry>
  82                 <entry>Edit</entry>
  83                 <entry>
  84             <para>
  85               Mark/unmark a packet.
  86             </para>
  87                 </entry>
  88               </row>
  89               <row>
  90                 <entry><command>Set Time Reference (toggle)</command></entry>
  91                 <entry>Edit</entry>
  92                 <entry>
  93             <para>
  94               Set/reset a time reference.
  95             </para>
  96                 </entry>
  97               </row>
  98               <row>
  99                 <entry>-----</entry>
 100                 <entry></entry>
 101                 <entry></entry>
 102               </row>
 103               <row>
 104                 <entry><command>Apply as Filter</command></entry>
 105                 <entry>Analyze</entry>
 106                 <entry>
 107             <para>
 108                   Prepare and apply a display filter based on the currently selected
 109                   item.
 110             </para>
 111                 </entry>
 112               </row>
 113               <row>
 114                 <entry><command>Prepare a Filter</command></entry>
 115                 <entry>Analyze</entry>
 116                 <entry>
 117             <para>
 118                   Prepare a display filter based on the currently selected item.
 119             </para>
 120                 </entry>
 121               </row>
 122               <row>
 123                 <entry><command>Conversation Filter</command></entry>
 124                 <entry>-</entry>
 125                 <entry>
 126             <para>
 127               This menu item applies a display filter with the address information
 128                   from the selected packet. E.g. the IP menu entry will set a filter
 129                   to show the traffic between the two IP addresses of the current
 130                   packet.
 131                   XXX - add a new section describing this better.
 132             </para>
 133                 </entry>
 134               </row>
 135               <row>
 136                 <entry><command>SCTP</command></entry>
 137                 <entry>-</entry>
 138                 <entry>
 139             <para>
 140                   XXX - add an explanation of this.
 141             </para>
 142                 </entry>
 143               </row>
 144               <row>
 145                 <entry><command>Follow TCP Stream</command></entry>
 146                 <entry>Analyze</entry>
 147                 <entry>
 148             <para>
 149                   Allows you to view all the data on a TCP
 150               stream between a pair of nodes.
 151             </para>
 152                 </entry>
 153               </row>
 154               <row>
 155                 <entry><command>Follow SSL Stream</command></entry>
 156                 <entry>Analyze</entry>
 157                 <entry>
 158             <para>
 159               Same as "Follow TCP Stream" but for SSL.
 160                   XXX - add a new section describing this better.
 161             </para>
 162                 </entry>
 163               </row>
 164               <row>
 165                 <entry>-----</entry>
 166                 <entry></entry>
 167                 <entry></entry>
 168               </row>
 169                   <row>
 170                 <entry><command>Copy/ Summary (Text)</command></entry>
 171                 <entry>-</entry>
 172                 <entry>
 173                 <para>
 174                   Copy the summary fields as displayed to the clipboard, as tab-separated text.
 175                 </para>
 176                 </entry>
 177                   </row>
 178                   <row>
 179                 <entry><command>Copy/ Summary (CSV)</command></entry>
 180                 <entry>-</entry>
 181                 <entry>
 182                 <para>
 183                   Copy the summary fields as displayed to the clipboard, as comma-separated text.
 184                 </para>
 185                 </entry>
 186                   </row>
 187                   <row>
 188                     <entry><command>Copy/ As Filter</command></entry>
 189                     <entry></entry>
 190                     <entry>
 191                     <para>
 192                       Prepare a display filter based on the currently selected item
 193                       and copy that filter to the clipboard.
 194                     </para>
 195                     </entry>
 196                   </row>
 197                   <row>
 198                 <entry><command>Copy/ Bytes (Offset Hex Text)</command></entry>
 199                 <entry>-</entry>
 200                 <entry>
 201                 <para>
 202                   Copy the packet bytes to the clipboard in hexdump-like format.
 203                 </para>
 204                 </entry>
 205                   </row>
 206                   <row>
 207                 <entry><command>Copy/ Bytes (Offset Hex)</command></entry>
 208                 <entry>-</entry>
 209                 <entry>
 210                 <para>
 211                   Copy the packet bytes to the clipboard in hexdump-like format, but without the text portion.
 212                 </para>
 213                 </entry>
 214                   </row>
 215                   <row>
 216                 <entry><command>Copy/ Bytes (Printable Text Only)</command></entry>
 217                 <entry>-</entry>
 218                 <entry>
 219                 <para>
 220                   Copy the packet bytes to the clipboard as ASCII text, excluding non-printable characters.
 221                 </para>
 222                 </entry>
 223                   </row>
 224                   <row>
 225                 <entry><command>Copy/ Bytes (Hex Stream)</command></entry>
 226                 <entry>-</entry>
 227                 <entry>
 228                 <para>
 229                   Copy the packet bytes to the clipboard as an unpunctuated list of hex digits.
 230                 </para>
 231                 </entry>
 232                   </row>
 233                   <row>
 234                 <entry><command>Copy/ Bytes (Binary Stream)</command></entry>
 235                 <entry>-</entry>
 236                 <entry>
 237                 <para>
 238                   Copy the packet bytes to the clipboard as raw binary. The data is stored in the
 239                   clipboard as MIME-type "application/octet-stream".</para>
 240                 <para>This option is not available in versions of Wireshark built using GTK+ 1.x.</para>
 241                 </entry>
 242                   </row>
 243               <row>
 244                 <entry><command>Export Selected Packet Bytes...</command></entry>
 245                 <entry>File</entry>
 246                 <entry>
 247             <para>
 248               This menu item is the same as the File menu item of the same
 249               name. It allows you to export raw packet bytes to a binary file.
 250             </para>
 251                 </entry>
 252               </row>
 253               <row>
 254                 <entry>-----</entry>
 255                 <entry></entry>
 256                 <entry></entry>
 257               </row>
 258               <row>
 259                 <entry><command>Decode As...</command></entry>
 260                 <entry>Analyze</entry>
 261                 <entry>
 262             <para>
 263                   Change or apply a new relation between two dissectors.
 264             </para>
 265                 </entry>
 266               </row>
 267               <row>
 268                 <entry><command>Print...</command></entry>
 269                 <entry>File</entry>
 270                 <entry>
 271             <para>
 272                   Print packets.
 273             </para>
 274                 </entry>
 275               </row>
 276               <row>
 277                 <entry><command>Show Packet in New Window</command></entry>
 278                 <entry>View</entry>
 279                 <entry>
 280             <para>
 281                   Display the selected packet in a new window.
 282             </para>
 283                 </entry>
 284               </row>
 285             </tbody>
 286           </tgroup>
 287         </table>
 288   </section>
 289
 290   <section id="ChWorkPacketDetailsPanePopUpMenuSection">
 291     <title>Pop-up menu of the "Packet Details" pane</title>
 292     <para>
 293       <figure id="ChWorkPacketDetailsPanePopUpMenu">
 294         <title>Pop-up menu of the "Packet Details" pane</title>
 295         <graphic entityref="WiresharkDetailsPanePopupMenu" format="PNG"/>
 296       </figure>
 297           </para>
 298           <para>
 299           The following table gives an overview of which functions are available
 300           in this pane, where to find the corresponding function in the main menu,
 301           and a short description of each item.
 302           </para>
 303         <table id="PacketDetailsPopupMenuTable">
 304           <title>The menu items of the "Packet Details" pop-up menu</title>
 305           <tgroup cols="3">
 306                 <colspec colnum="1" colwidth="80pt"/>
 307                 <colspec colnum="2" colwidth="80pt"/>
 308             <thead>
 309               <row>
 310                 <entry>Item</entry>
 311                 <entry>Identical to main menu's item:</entry>
 312                 <entry>Description</entry>
 313               </row>
 314             </thead>
 315             <tbody>
 316               <row>
 317                 <entry><command>Expand Subtrees</command></entry>
 318                 <entry>View</entry>
 319                 <entry>
 320             <para>
 321               Expand the currently selected subtree.
 322             </para>
 323                 </entry>
 324               </row>
 325               <row>
 326                 <entry><command>Expand All</command></entry>
 327                 <entry>View</entry>
 328                 <entry>
 329             <para>
 330               Expand all subtrees in all packets in the capture.
 331             </para>
 332                 </entry>
 333               </row>
 334               <row>
 335                 <entry><command>Collapse All</command></entry>
 336                 <entry>View</entry>
 337                 <entry>
 338             <para>
 339               Wireshark keeps a list of all the protocol subtrees that are
 340               expanded, and uses it to ensure that the correct subtrees
 341               are expanded when you display a packet. This menu item
 342               collapses the tree view of all packets in the capture list.
 343             </para>
 344                 </entry>
 345               </row>
 346               <row>
 347                 <entry>-----</entry>
 348                 <entry></entry>
 349                 <entry></entry>
 350               </row>
 351               <row>
 352                 <entry><command>Copy/ Description</command></entry>
 353                 <entry>-</entry>
 354                 <entry>
 355             <para>
 356               Copy the displayed text of the selected field to the system
 357                   clipboard.
 358             </para>
 359                 </entry>
 360               </row>
 361               <row>
 362                 <entry><command>Copy/ As Filter</command></entry>
 363                 <entry>Edit</entry>
 364                 <entry>
 365             <para>
 366                   Prepare a display filter based on the currently selected item
 367                   and copy it to the clipboard.
 368             </para>
 369                 </entry>
 370               </row>
 371                   <row>
 372                 <entry><command>Copy/ Bytes (Offset Hex Text)</command></entry>
 373                 <entry>-</entry>
 374                 <entry>
 375                 <para>
 376                   Copy the packet bytes to the clipboard in hexdump-like format; similar to the Packet List Pane
 377                   command, but copies only the bytes relevant to the selected part of the tree (the bytes selected
 378                   in the Packet Bytes Pane).
 379                 </para>
 380                 </entry>
 381                   </row>
 382                   <row>
 383                 <entry><command>Copy/ Bytes (Offset Hex)</command></entry>
 384                 <entry>-</entry>
 385                 <entry>
 386                 <para>
 387                   Copy the packet bytes to the clipboard in hexdump-like format, but without the text portion; similar to the           Packet List Pane
 388                   command, but copies only the bytes relevant to the selected part of the tree (the bytes selected
 389                   in the Packet Bytes Pane).
 390                 </para>
 391                 </entry>
 392                   </row>
 393                   <row>
 394                 <entry><command>Copy/ Bytes (Printable Text Only)</command></entry>
 395                 <entry>-</entry>
 396                 <entry>
 397                 <para>
 398                   Copy the packet bytes to the clipboard as ASCII text, excluding non-printable characters; similar to the Packet List Pane
 399                   command, but copies only the bytes relevant to the selected part of the tree (the bytes selected
 400                   in the Packet Bytes Pane).
 401                 </para>
 402                 </entry>
 403                   </row>
 404                   <row>
 405                 <entry><command>Copy/ Bytes (Hex Stream)</command></entry>
 406                 <entry>-</entry>
 407                 <entry>
 408                 <para>
 409                   Copy the packet bytes to the clipboard as an unpunctuated list of hex digits; similar to the Packet List Pane
 410                   command, but copies only the bytes relevant to the selected part of the tree (the bytes selected
 411                   in the Packet Bytes Pane).
 412                 </para>
 413                 </entry>
 414                   </row>
 415                   <row>
 416                 <entry><command>Copy/ Bytes (Binary Stream)</command></entry>
 417                 <entry>-</entry>
 418                 <entry>
 419                 <para>
 420                   Copy the packet bytes to the clipboard as raw binary; similar to the Packet List Pane
 421                   command, but copies only the bytes relevant to the selected part of the tree (the bytes selected
 422                   in the Packet Bytes Pane). The data is stored in the
 423                   clipboard as MIME-type "application/octet-stream".</para>
 424                 <para>This option is not available in versions of Wireshark built using GTK+ 1.x.</para>
 425                 </entry>
 426                   </row>
 427               <row>
 428                 <entry><command>Export Selected Packet Bytes...</command></entry>
 429                 <entry>File</entry>
 430                 <entry>
 431             <para>
 432               This menu item is the same as the File menu item of the same
 433               name. It allows you to export raw packet bytes to a binary file.
 434             </para>
 435                 </entry>
 436               </row>
 437               <row>
 438                 <entry>-----</entry>
 439                 <entry></entry>
 440                 <entry></entry>
 441               </row>
 442               <row>
 443                 <entry><command>Apply as Filter</command></entry>
 444                 <entry>Analyze</entry>
 445                 <entry>
 446             <para>
 447               Prepare and apply a display filter based on the currently
 448                         selected item.
 449             </para>
 450                 </entry>
 451               </row>
 452               <row>
 453                 <entry><command>Prepare a Filter</command></entry>
 454                 <entry>Analyze</entry>
 455                 <entry>
 456             <para>
 457                   Prepare a display filter based on the currently selected item.
 458             </para>
 459                 </entry>
 460               </row>
 461               <row>
 462                 <entry><command>Follow TCP Stream</command></entry>
 463                 <entry>Analyze</entry>
 464                 <entry>
 465             <para>
 466                   Allows you to view all the data on a TCP stream between a pair
 467                   of nodes.
 468                 </para>
 469                 </entry>
 470               </row>
 471               <row>
 472                 <entry><command>Follow SSL Stream</command></entry>
 473                 <entry>Analyze</entry>
 474                 <entry>
 475             <para>
 476               Same as "Follow TCP Stream" but for SSL.
 477                   XXX - add a new section describing this better.
 478             </para>
 479                 </entry>
 480               </row>
 481               <row>
 482                 <entry>-----</entry>
 483                 <entry></entry>
 484                 <entry></entry>
 485               </row>
 486               <row>
 487                 <entry><command>Wiki Protocol Page</command></entry>
 488                 <entry>-</entry>
 489                 <entry>
 490             <para>
 491               Show the wiki page corresponding to the currently selected protocol
 492                   in your web browser.
 493             </para>
 494                 </entry>
 495               </row>
 496               <row>
 497                 <entry><command>Filter Field Reference</command></entry>
 498                 <entry>-</entry>
 499                 <entry>
 500             <para>
 501                   Show the filter field reference web page corresponding to the
 502                   currently selected protocol in your web browser.
 503             </para>
 504                 </entry>
 505               </row>
 506               <row>
 507                 <entry><command>Protocol Preferences...</command></entry>
 508                 <entry>-</entry>
 509                 <entry>
 510             <para>
 511               The menu item takes you to the properties dialog and selects the
 512                   page corresponding to the protocol if there are properties
 513                   associated with the highlighted field.
 514               More information on preferences can be found in
 515               <xref linkend="ChCustGUIPrefPage"/>.
 516             </para>
 517                 </entry>
 518               </row>
 519               <row>
 520                 <entry>-----</entry>
 521                 <entry></entry>
 522                 <entry></entry>
 523               </row>
 524               <row>
 525                 <entry><command>Decode As...</command></entry>
 526                 <entry>Analyze</entry>
 527                 <entry>
 528             <para>
 529                   Change or apply a new relation between two dissectors.
 530             </para>
 531                 </entry>
 532               </row>
 533               <row>
 534                 <entry><command>Resolve Name</command></entry>
 535                 <entry>View</entry>
 536                 <entry>
 537             <para>
 538               Causes a name resolution to be performed for
 539               the selected packet, but NOT every packet in the capture.
 540             </para>
 541                 </entry>
 542               </row>
 543               <row>
 544                 <entry><command>Go to Corresponding Packet</command></entry>
 545                 <entry>Go</entry>
 546                 <entry>
 547             <para>
 548               If the selected field has a corresponding packet, go to it.
 549                   Corresponding packets will usually be a request/response packet pair
 550                   or such.
 551             </para>
 552                 </entry>
 553               </row>
 554                 </tbody>
 555           </tgroup>
 556         </table>
 557   </section>
 558
 559   </section>
 560
 561   <section id="ChWorkDisplayFilterSection">
 562     <title>Filtering packets while viewing</title>
 563     <para>
 564       Wireshark has two filtering languages: One used when capturing
 565       packets, and one used when displaying packets.  In this section we
 566       explore that second type of filter: Display filters.  The first one
 567       has already been dealt with in
 568           <xref linkend="ChCapCaptureFilterSection"/>.
 569     </para>
 570     <para>
 571       Display filters allow you to concentrate on the packets you are
 572       interested in while hiding the currently uninteresting ones. They allow
 573           you to select packets by:
 574         <itemizedlist>
 575           <listitem><para>Protocol</para></listitem>
 576           <listitem><para>The presence of a field</para></listitem>
 577           <listitem><para>The values of fields</para></listitem>
 578           <listitem><para>A comparison between fields</para></listitem>
 579           <listitem><para>... and a lot more!</para></listitem>
 580       </itemizedlist>
 581     </para>
 582     <para>
 583       To select packets based on protocol type, simply type the protocol in which you
 584       are interested in the <command>Filter:</command> field in the filter
 585           toolbar of the Wireshark window and press enter to initiate
 586       the filter. <xref linkend="ChWorkTCPFilter"/> shows an example of what
 587         happens when you type <command>tcp</command> in the filter field.
 588     </para>
 589     <note>
 590       <title>Note!</title>
 591       <para>
 592         All protocol and field names are entered in lowercase.  Also, don't
 593         forget to press enter after entering the filter expression.
 594       </para>
 595     </note>
 596     <figure id="ChWorkTCPFilter"><title>Filtering on the TCP protocol</title>
 597       <graphic entityref="WiresharkFilterTCP" format="JPG"/>
 598     </figure>
 599     <para>
 600         As you might have noticed, only packets of the TCP protocol are displayed
 601         now (e.g. packets 1-10 are hidden). The packet numbering will remain as
 602         before, so the first packet shown is now packet number 11.
 603     </para>
 604     <note>
 605       <title>Note!</title>
 606       <para>
 607           When using a display filter, all packets remain in the capture file.
 608           The display filter only changes the display of the capture file but
 609           not its content!
 610       </para>
 611     </note>
 612     <para>
 613       You can filter on any protocol that Wireshark understands.
 614       You can also filter on any field that a dissector adds to the tree
 615       view, but only if the dissector has added an abbreviation for the
 616       field. A list of such fields is available in Wireshark in the
 617       <command>Add Expression...</command> dialog box.  You can find more
 618       information on the <command>Add Expression...</command> dialog box
 619       in <xref linkend="ChWorkFilterAddExpressionSection"/>.
 620     </para>
 621     <para>
 622       For example, to narrow the packet list pane down to only those
 623       packets to or from the IP address 192.168.0.1, use
 624       <command>ip.addr==192.168.0.1</command>.
 625     </para>
 626     <note>
 627       <title>Note!</title>
 628       <para>
 629         To remove the filter, click on the <command>Clear</command> button
 630         to the right of the filter field.
 631       </para>
 632     </note>
 633     </section>
 634
 635     <section id="ChWorkBuildDisplayFilterSection">
 636       <title>Building display filter expressions</title>
 637       <para>
 638         Wireshark provides a simple but powerful display filter language that allows you
 639         to build quite complex filter expressions.  You can compare
 640         values in packets as well as combine expressions into more
 641         specific expressions.  The following sections provide more
 642         information on doing this.
 643       </para>
 644     <tip>
 645       <title>Tip!</title>
 646       <para>
 647           You will find a lot of Display Filter examples at the <command>Wireshark
 648           Wiki Display Filter page</command> at <ulink
 649           url="&WiresharkWikiDisplayFiltersPage;">&WiresharkWikiDisplayFiltersPage;</ulink>.
 650       </para>
 651     </tip>
 652       <section>
 653         <title>Display filter fields</title>
 654         <para>
 655         Every field in the packet details pane can be used as a filter
 656         string, this will result in showing only the packets where this field
 657         exists. For example: the
 658         filter string: <command>tcp</command> will show all packets containing the
 659         tcp protocol.
 660         </para>
 661         <para>
 662         There is a complete list of all filter fields available
 663         through the menu item "Help/Supported Protocols" in the page "Display Filter
 664         Fields" of the Supported Protocols dialog.
 665         </para>
 666         <para>
 667         XXX - add some more info here and a link to the statusbar info.
 668         </para>
 669       </section>
 670       <section>
 671         <title>Comparing values</title>
 672         <para>
 673           You can build display filters that compare values using a number
 674           of different comparison operators.  They are shown in
 675           <xref linkend="DispCompOps"/>.
 676         </para>
 677         <tip><title>Tip!</title>
 678         <para>
 679         You can use English and C-like terms in the same way, they can even be
 680         mixed in a filter string!
 681         </para>
 682         </tip>
 683         <table id="DispCompOps">
 684           <title>Display Filter comparison operators</title>
 685           <tgroup cols="3">
 686                 <colspec colnum="1" colwidth="50pt"/>
 687                 <colspec colnum="2" colwidth="50pt"/>
 688             <thead>
 689               <row>
 690                 <entry>English</entry>
 691                 <entry>C-like</entry>
 692                 <entry>Description and example</entry>
 693               </row>
 694             </thead>
 695             <tbody>
 696               <row>
 697                 <entry>eq</entry>
 698                 <entry><programlisting>==</programlisting></entry>
 699                 <entry><para>
 700                     <command>Equal</command></para><para>
 701                     <programlisting>ip.addr==10.0.0.5</programlisting>
 702                   </para></entry>
 703               </row>
 704               <row>
 705                 <entry>ne</entry>
 706                 <entry><programlisting>!=</programlisting></entry>
 707                 <entry><para>
 708                     <command>Not equal</command></para><para>
 709                     <programlisting>ip.addr!=10.0.0.5</programlisting>
 710                   </para></entry>
 711               </row>
 712               <row>
 713                 <entry>gt</entry>
 714                 <entry><programlisting>&gt;</programlisting></entry>
 715                 <entry><para>
 716                     <command>Greater than</command></para><para>
 717                     <programlisting>frame.pkt_len &gt; 10</programlisting>
 718                   </para></entry>
 719               </row>
 720               <row>
 721                 <entry>lt</entry>
 722                 <entry><programlisting>&lt;</programlisting></entry>
 723                 <entry><para><command>Less than</command></para><para>
 724                     <programlisting>frame.pkt_len &lt; 128</programlisting>
 725                   </para></entry>
 726               </row>
 727               <row>
 728                 <entry>ge</entry>
 729                 <entry><programlisting>&gt;=</programlisting></entry>
 730                 <entry><para>
 731                     <command>Greater than or equal to</command></para><para>
 732                     <programlisting>frame.pkt_len ge 0x100</programlisting>
 733                   </para></entry>
 734               </row>
 735               <row>
 736                 <entry>le</entry>
 737                 <entry><programlisting>&lt;=</programlisting></entry>
 738                 <entry><para>
 739                     <command>Less than or equal to</command></para><para>
 740                     <programlisting>frame.pkt_len &lt;= 0x20</programlisting>
 741                   </para></entry>
 742               </row>
 743             </tbody>
 744           </tgroup>
 745         </table>
 746         <para>
 747           In addition, all protocol fields are typed.
 748           <xref linkend="ChWorkFieldTypes"/> provides a list of the types and
 749             example of how to express them.
 750             <table id="ChWorkFieldTypes">
 751               <title>Display Filter Field Types</title>
 752               <tgroup cols="2">
 753                 <thead>
 754                   <row>
 755                     <entry>Type</entry>
 756                     <entry>Example</entry>
 757                   </row>
 758                 </thead>
 759                 <tbody>
 760                   <row>
 761                     <entry>
 762                       Unsigned integer (8-bit, 16-bit, 24-bit, 32-bit)
 763                     </entry>
 764                     <entry><para>
 765                         You can express integers in decimal, octal, or
 766                         hexadecimal. The following display filters are
 767                         equivalent:
 768                         <programlisting>
 769 ip.len le 1500
 770 ip.len le 02734
 771 ip.len le 0x436
 772                         </programlisting>
 773                       </para></entry>
 774                   </row>
 775                   <row>
 776                     <entry>
 777                       Signed integer (8-bit, 16-bit, 24-bit, 32-bit)
 778                     </entry>
 779                     <entry></entry>
 780                   </row>
 781                   <row>
 782                     <entry>Boolean</entry>
 783                     <entry><para>
 784                         A boolean field is present in the protocol decode
 785                         only if its value is true. For example,
 786                         <command>tcp.flags.syn</command> is present, and
 787                         thus true, only if the SYN flag is present in a
 788                         TCP segment header.</para><para>
 789                         Thus the filter expression
 790                         <command>tcp.flags.syn</command> will select only
 791                         those packets for which this flag exists, that is,
 792                         TCP segments where the segment header contains the
 793                         SYN flag. Similarly, to find source-routed token
 794                         ring packets, use a filter expression of
 795                         <command>tr.sr</command>.
 796                       </para></entry>
 797                   </row>
 798                   <row>
 799                     <entry>Ethernet address (6 bytes)</entry>
 800                     <entry><para>Separators can be a colon
 801                         (:), dot (.) or dash (-) and can have one or
 802                         two bytes between separators:<programlisting>
 803 eth.addr == ff:ff:ff:ff:ff:ff
 804 eth.addr == ff-ff-ff-ff-ff-ff
 805 eth.addr == ffff.ffff.ffff</programlisting></para></entry>
 806                   </row>
 807                   <row>
 808                     <entry>IPv4 address</entry>
 809                     <entry>
 810                 <para>ip.addr == 192.168.0.1</para>
 811                 <para>Classless InterDomain Routing (CIDR) notation
 812                 can be used to test if an IPv4 address is in a
 813                 certain subnet. For example, this display filter
 814                 will find all packets in the 129.111 Class-B
 815                 network:
 816                 </para><para>ip.addr == 129.111.0.0/16</para></entry>
 817                   </row>
 818                   <row>
 819                     <entry>IPv6 address</entry>
 820                     <entry>ipv6.addr == ::1</entry>
 821                   </row>
 822                   <row>
 823                     <entry>IPX address</entry>
 824                     <entry>ipx.addr == 00000000.ffffffffffff</entry>
 825                   </row>
 826                   <row>
 827                     <entry>String (text)</entry>
 828                     <entry>http.request.uri == "http://www.wireshark.org/"</entry>
 829                   </row>
 830                 </tbody>
 831               </tgroup>
 832             </table>
 833         </para>
 834       </section>
 835       <section>
 836         <title>Combining expressions</title>
 837         <para>
 838           You can combine filter expressions in Wireshark using the
 839           logical operators shown in <xref linkend="FiltLogOps"/>
 840         </para>
 841         <table id="FiltLogOps">
 842           <title>Display Filter Logical Operations</title>
 843           <tgroup cols="3">
 844                 <colspec colnum="1" colwidth="50pt"/>
 845                 <colspec colnum="2" colwidth="50pt"/>
 846             <thead>
 847               <row>
 848                 <entry>English</entry>
 849                 <entry>C-like</entry>
 850                 <entry>Description and example</entry>
 851               </row>
 852             </thead>
 853             <tbody>
 854               <row>
 855                 <entry>and</entry>
 856                 <entry>&amp;&amp;</entry>
 857                 <entry><para>
 858                     <command>Logical AND</command></para><para>
 859                     <programlisting>ip.addr==10.0.0.5 and tcp.flags.fin</programlisting>
 860                   </para></entry>
 861               </row>
 862               <row>
 863                 <entry>or</entry>
 864                 <entry>||</entry>
 865                 <entry><para>
 866                     <command>Logical OR</command></para><para>
 867                     <programlisting>ip.addr==10.0.0.5 or ip.addr==192.1.1.1</programlisting>
 868                   </para></entry>
 869               </row>
 870               <row>
 871                 <entry>xor</entry>
 872                 <entry>^^</entry>
 873                 <entry><para>
 874                     <command>Logical XOR</command></para><para>
 875                     <programlisting>tr.dst[0:3] == 0.6.29 xor tr.src[0:3] == 0.6.29</programlisting>
 876                   </para></entry>
 877               </row>
 878               <row>
 879                 <entry>not</entry>
 880                 <entry>!</entry>
 881                 <entry><para>
 882                     <command>Logical NOT</command></para><para>
 883                     <programlisting>not llc</programlisting>
 884                   </para></entry>
 885               </row>
 886               <row>
 887                 <entry>[...]</entry>
 888                 <entry></entry>
 889                 <entry><para>
 890                     <command>Substring Operator</command></para><para>
 891                     Wireshark allows you to select subsequences of a
 892                     sequence in rather elaborate ways.  After a label you
 893                     can place a pair of brackets [] containing a comma
 894                     separated list of range specifiers. </para><para>
 895                     <programlisting>eth.src[0:3] == 00:00:83</programlisting></para><para>
 896                     The example above uses the n:m format to specify a
 897                     single range.  In this case n is the beginning offset
 898                     and m is the length of the range
 899                     being specified.</para><para>
 900                     <programlisting>
 901 eth.src[1-2] == 00:83
 902                     </programlisting></para><para>
 903                     The example above uses the n-m format to specify a
 904                     single range. In this case n is the beginning offset
 905                     and m is the ending offset. </para><para>
 906                     <programlisting>eth.src[:4] == 00:00:83:00</programlisting></para><para>
 907                     The example above uses the :m format, which takes
 908                     everything from the beginning of a sequence to offset m.
 909                     It is equivalent to 0:m</para><para>
 910                     <programlisting>eth.src[4:] == 20:20</programlisting></para><para>
 911                     The example above uses the n: format, which takes
 912                     everything from offset n to the end of the
 913                     sequence. </para><para>
 914                     <programlisting>eth.src[2] == 83</programlisting></para><para>
 915                     The example above uses the n format to specify a
 916                     single range.  In this case the element in the
 917                     sequence at offset n is selected.  This is equivalent
 918                     to n:1.</para><para>
 919                     <programlisting>eth.src[0:3,1-2,:4,4:,2] ==
 920 00:00:83:00:83:00:00:83:00:20:20:83</programlisting></para><para>
 921                     Wireshark allows you to string together single ranges
 922                     in a comma separated list to form compound ranges as
 923                     shown above.
 924                   </para></entry>
 925               </row>
 926             </tbody>
 927           </tgroup>
 928         </table>
 929       </section>
 930       <section><title>A common mistake</title>
 931           <warning><title>Warning!</title>
 932           <para>
 933           Using the != operator on combined expressions like: eth.addr, ip.addr,
 934           tcp.port, udp.port and alike will probably not work as expected!
 935           </para>
 936           </warning>
 937           <para>
 938           Often people use a filter string to display something like
 939           <command>ip.addr == 1.2.3.4</command> which will display all packets
 940           containing the IP address 1.2.3.4.
 941           </para>
 942           <para>
 943           Then they use <command>ip.addr != 1.2.3.4</command> to see all packets
 944           not containing the IP address 1.2.3.4 in it. Unfortunately, this does
 945           <command>not</command> do the expected.
 946           </para>
 947           <para>
 948         Instead, that expression will even be true for packets where either
 949         source or destination IP address equals 1.2.3.4. The reason for this,
 950         is that the expression <command>ip.addr != 1.2.3.4</command> must be read as "the
 951         packet contains a field named ip.addr with a value
 952         different from 1.2.3.4". As an IP datagram contains both a source and
 953         a destination address, the expression will evaluate to true whenever
 954         at least one of the two addresses differs from 1.2.3.4.
 955           </para>
 956           <para>
 957         If you want to
 958         filter out all packets containing IP datagrams to or from IP address
 959         1.2.3.4, then the correct filter is <command>!(ip.addr == 1.2.3.4)</command> as it
 960         reads "show me all the packets for which it is not true
 961         that a field named ip.addr exists with a value of 1.2.3.4", or in
 962         other words, "filter out all packets for which there are
 963         no occurrences of a field named ip.addr with the value 1.2.3.4".
 964           </para>
 965       </section>
 966   </section>
 967
 968   <section id="ChWorkFilterAddExpressionSection">
 969   <title>The "Filter Expression" dialog box</title>
 970     <para>
 971       When you are accustomed to Wireshark's filtering system and know what
 972       labels you wish to use in your filters it can be very quick to
 973       simply type a filter string.  However if you are new to Wireshark or
 974       are working with a slightly unfamiliar protocol it can be very
 975       confusing to try to figure out what to type.  The Filter Expression
 976       dialog box helps with this.
 977     </para>
 978     <tip><title>Tip!</title>
 979         <para>
 980       The "Filter Expression" dialog box is an excellent way to learn how to
 981           write Wireshark display filter strings.
 982         </para>
 983     </tip>
 984     <figure id="ChWorkFilterAddExpression1">
 985       <title>The "Filter Expression" dialog box</title>
 986       <graphic entityref="WiresharkFilterAddExpression" format="PNG"/>
 987     </figure>
 988     <para>
 989       When you first bring up the Filter Expression dialog box you are shown a
 990       tree list of field names, organized by protocol, and a box for
 991       selecting a relation.
 992     </para>
 993     <variablelist>
 994       <varlistentry><term><command>Field Name</command></term>
 995         <listitem>
 996           <para>
 997             Select a protocol field from the protocol field tree.
 998             Every protocol with filterable fields is listed at the
 999             top level.  (You can search for a particular protocol
1000             entry by entering the first few letters of the protocol name).
1001             By clicking on the "+" next to a protocol name
1002             you can get a list of the field names available for filtering
1003             for that protocol.
1004           </para>
1005         </listitem>
1006       </varlistentry>
1007       <varlistentry><term><command>Relation</command></term>
1008         <listitem>
1009           <para>
1010             Select a relation from the list of available relation.
1011             The <command>is present</command> is a unary relation which
1012             is true if the selected field is present in a packet.  All
1013             other listed relations are binary relations which require additional
1014             data (e.g. a <command>Value</command> to match) to complete.
1015           </para>
1016         </listitem>
1017       </varlistentry>
1018     </variablelist>
1019     <para>
1020       When you select a field from the field name list and select a
1021       binary relation (such as the equality relation ==) you will be
1022       given the opportunity to enter a value, and possibly some range
1023       information.
1024     </para>
1025     <variablelist>
1026       <varlistentry><term><command>Value</command></term>
1027         <listitem>
1028           <para>
1029             You may enter an appropriate value in the
1030             <command>Value</command> text box.  The <command>Value</command>
1031             will also indicate the type of value for the
1032             <command>field name</command> you have selected (like
1033             character string).
1034           </para>
1035         </listitem>
1036       </varlistentry>
1037       <varlistentry><term><command>Predefined values</command></term>
1038         <listitem>
1039           <para>
1040           Some of the protocol fields have predefined values available, much like
1041           enum's in C. If the selected protocol field has such values defined, you
1042           can choose one of them here.
1043           </para>
1044         </listitem>
1045       </varlistentry>
1046       <varlistentry><term><command>Range</command></term>
1047         <listitem>
1048           <para>
1049           XXX - add an explanation here!
1050           </para>
1051         </listitem>
1052       </varlistentry>
1053       <varlistentry><term><command>OK</command></term>
1054         <listitem>
1055           <para>
1056             When you have built a satisfactory expression click
1057             <command>OK</command> and a filter string will be
1058             built for you.
1059           </para>
1060         </listitem>
1061       </varlistentry>
1062       <varlistentry><term><command>Cancel</command></term>
1063         <listitem>
1064           <para>
1065             You can leave the <command>Add Expression...</command> dialog
1066             box without any effect by clicking the <command>Cancel</command>
1067                 button.
1068           </para>
1069         </listitem>
1070       </varlistentry>
1071     </variablelist>
1072   </section>
1073
1074   <section id="ChWorkDefineFilterSection"><title>Defining and saving filters</title>
1075     <para>
1076       You can define filters with Wireshark and give them labels for
1077       later use.  This can save time in remembering and retyping some of
1078       the more complex filters you use.
1079     </para>
1080     <para>
1081       To define a new filter or edit an existing one, select the
1082       <command>Capture Filters...</command> menu item from the Capture menu
1083           or the <command>Display Filters...</command> menu item from the Analyze
1084           menu. Wireshark will then pop up the Filters dialog as shown in
1085           <xref linkend="FiltersDialog"/>.
1086     </para>
1087         <note>
1088           <title>Note!</title>
1089           <para>
1090                 The mechanisms for defining and saving capture filters and display
1091                 filters are almost identical. So both will be described here,
1092                 differences between these two will be marked as such.
1093           </para>
1094         </note>
1095         <warning><title>Warning!</title>
1096         <para>
1097         You must use <command>Save</command> to save your filters permanently.
1098         <command>Ok</command> or <command>Apply</command> will not save the filters,
1099         so they will be lost when you close Wireshark.
1100         </para>
1101         </warning>
1102     <figure id="FiltersDialog">
1103       <title>The "Capture Filters" and "Display Filters" dialog boxes</title>
1104       <graphic entityref="WiresharkFilters" format="PNG"/>
1105     </figure>
1106     <para>
1107       <variablelist>
1108         <varlistentry><term><command>New</command></term>
1109           <listitem>
1110             <para>
1111               This button adds a new filter to the list of filters. The currently
1112                   entered values from Filter name and Filter string will be used. If
1113                   any of these fields are empty, it will be set to "new".
1114             </para>
1115           </listitem>
1116         </varlistentry>
1117         <varlistentry><term><command>Delete</command></term>
1118           <listitem>
1119           <para>
1120           This button deletes the selected filter. It will be greyed out, if no
1121           filter is selected.
1122           </para>
1123           </listitem>
1124         </varlistentry>
1125         <varlistentry><term><command>Filter</command></term>
1126           <listitem>
1127             <para>
1128                 You can select a filter from this list (which will fill in the
1129                 filter name and filter string in the fields down at the bottom of the
1130                 dialog box).
1131             </para>
1132           </listitem>
1133         </varlistentry>
1134         <varlistentry><term><command>Filter name:</command></term>
1135           <listitem>
1136             <para>
1137                 You can change the name of the currently selected filter here.
1138             </para>
1139                 <note><title>Note!</title>
1140                 <para>
1141                 The filter name will only be used in this dialog to identify the
1142                 filter for your convenience, it will not be used elsewhere. You can
1143                 add multiple filters with the same name, but this is not very useful.
1144                 </para>
1145                 </note>
1146           </listitem>
1147         </varlistentry>
1148         <varlistentry><term><command>Filter string:</command></term>
1149           <listitem>
1150             <para>
1151                 You can change the filter string of the currently selected filter here.
1152                 Display Filter only: the string will be syntax checked while you are
1153                 typing.
1154             </para>
1155           </listitem>
1156         </varlistentry>
1157         <varlistentry><term><command>Add Expression...</command></term>
1158           <listitem>
1159             <para>
1160               Display Filter only: This button brings up the Add Expression
1161                   dialog box which assists in building filter strings.  You can find
1162                   more information about the Add Expression dialog in
1163               <xref linkend="ChWorkFilterAddExpressionSection"/>
1164             </para>
1165           </listitem>
1166         </varlistentry>
1167         <varlistentry><term><command>OK</command></term>
1168           <listitem>
1169             <para>
1170               Display Filter only: This button applies the selected filter to the
1171                   current display and closes the dialog.
1172             </para>
1173           </listitem>
1174         </varlistentry>
1175         <varlistentry><term><command>Apply</command></term>
1176           <listitem>
1177             <para>
1178               Display Filter only: This button applies the selected filter to the
1179                   current display, and keeps the dialog open.
1180             </para>
1181           </listitem>
1182         </varlistentry>
1183         <varlistentry><term><command>Save</command></term>
1184           <listitem>
1185             <para>
1186               Save the current settings in this dialog. The file location and
1187                   format is explained in <xref linkend="AppFiles"/>.
1188             </para>
1189           </listitem>
1190         </varlistentry>
1191         <varlistentry><term><command>Close</command></term>
1192           <listitem>
1193             <para>
1194               Close this dialog. This will discard unsaved settings.
1195             </para>
1196           </listitem>
1197         </varlistentry>
1198       </variablelist>
1199     </para>
1200   </section>
1201
1202   <section id="ChWorkFindPacketSection"><title>Finding packets</title>
1203     <para>
1204       You can easily find packets once you have captured some packets or
1205       have read in a previously saved capture file. Simply select the
1206       <command>Find Packet...</command> menu item from the
1207       <command>Edit</command> menu.  Wireshark will pop up the dialog box
1208       shown in <xref linkend="ChWorkFindPacketDialog"/>.
1209     </para>
1210         <section><title>The "Find Packet" dialog box</title>
1211     <figure id="ChWorkFindPacketDialog">
1212       <title>The "Find Packet" dialog box</title>
1213       <graphic entityref="WiresharkFindPacket" format="PNG"/>
1214     </figure>
1215     <para>
1216         You might first select the kind of thing to search for:
1217         <itemizedlist>
1218                 <listitem>
1219                         <para>
1220                 <command>Display filter</command>
1221                         </para>
1222                         <para>
1223                         Simply enter a display filter string into the
1224                         <command>Filter:</command> field, select a direction, and click on OK.
1225                         </para>
1226                         <para>
1227                         For example, to find the three way handshake for a connection from
1228                         host 192.168.0.1, use the following filter string:
1229                         <programlisting>ip.addr==192.168.0.1 and tcp.flags.syn</programlisting>
1230                         For more details on display filters, see <xref linkend="ChWorkDisplayFilterSection"/>
1231                         </para>
1232                 </listitem>
1233                 <listitem>
1234                         <para>
1235                 <command>Hex Value</command>
1236                         </para>
1237                         <para>
1238                         Search for a specific byte sequence in the packet data.
1239                         </para>
1240                         <para>
1241                         For example, use "00:00" to find the next packet including two
1242                         null bytes in the packet data.
1243                         </para>
1244                 </listitem>
1245                 <listitem>
1246                         <para>
1247                 <command>String</command>
1248                         </para>
1249                         <para>
1250                         Find a string in the packet data, with various options.
1251                         </para>
1252                 </listitem>
1253         </itemizedlist>
1254     </para>
1255     <para>
1256         The value to be found will be syntax checked while you type it in. If the
1257         syntax check of your value succeeds, the background of the entry field
1258         will turn green, if it fails, it will turn red.
1259         </para>
1260     <para>
1261         You can choose the search direction:
1262         <itemizedlist>
1263                 <listitem>
1264                 <para><command>Up</command></para>
1265                         <para>Search upwards in the packet list (decreasing packet numbers).</para>
1266                 </listitem>
1267         </itemizedlist>
1268         <itemizedlist>
1269                 <listitem>
1270                 <para><command>Down</command></para>
1271                         <para>Search downwards in the packet list (increasing packet numbers).</para>
1272                 </listitem>
1273         </itemizedlist>
1274         </para>
1275   </section>
1276   <section><title>The "Find Next" command</title>
1277     <para>
1278         "Find Next" will continue searching with the same options used in the last
1279         "Find Packet".
1280         </para>
1281   </section>
1282   <section><title>The "Find Previous" command</title>
1283     <para>
1284         "Find Previous" will do the same thing as "Find Next", but with reverse
1285         search direction.
1286         </para>
1287   </section>
1288   </section>
1289
1290   <section id="ChWorkGoToPacketSection"><title>Go to a specific packet</title>
1291   <para>
1292   You can easily jump to specific packets with one of the menu items in the
1293   Go menu.
1294   </para>
1295   <section><title>The "Go Back" command</title>
1296   <para>
1297   Go back in the packet history, works much like the page history in current
1298   web browsers.
1299   </para>
1300   </section>
1301   <section><title>The "Go Forward" command</title>
1302   <para>
1303   Go forward in the packet history, works much like the page history in
1304   current web browsers.
1305   </para>
1306   </section>
1307   <section><title>The "Go to Packet" dialog box</title>
1308     <figure id="ChWorkGoToPacketDialog">
1309       <title>The "Go To Packet" dialog box</title>
1310       <graphic entityref="WiresharkGoToPacket" format="PNG"/>
1311     </figure>
1312     <para>
1313         This dialog box will let you enter a packet number. When you press
1314         <command>OK</command>, Wireshark will jump to that packet.
1315         </para>
1316   </section>
1317   <section><title>The "Go to Corresponding Packet" command</title>
1318     <para>
1319         If a protocol field is selected which points to another packet in the
1320         capture file, this command will jump to that packet.
1321         </para>
1322     <note><title>Note!</title>
1323     <para>
1324         As these protocol fields now work like links (just as in your
1325         Web browser), it's easier to simply double-click on the field to jump
1326         to the corresponding field.
1327     </para>
1328     </note>
1329   </section>
1330   <section><title>The "Go to First Packet" command</title>
1331     <para>
1332         This command will simply jump to the first packet displayed.
1333         </para>
1334   </section>
1335   <section><title>The "Go to Last Packet" command</title>
1336     <para>
1337         This command will simply jump to the last packet displayed.
1338         </para>
1339   </section>
1340   </section>
1341
1342   <section id="ChWorkMarkPacketSection"><title>Marking packets</title>
1343     <para>
1344         You can mark packets in the "Packet List" pane. A marked packet will
1345         be shown with black background, regardless of the coloring rules set.
1346         Marking a packet can be useful to find it later while analyzing in a large
1347         capture file.
1348     </para>
1349     <warning><title>Warning!</title>
1350     <para>
1351         The packet marks are not stored in the capture file or anywhere else,
1352         so all packet marks will be lost if you close the capture file.
1353     </para>
1354     </warning>
1355     <para>
1356         You can use packet marking to control the output of packets when
1357         saving/exporting/printing. To do so, an option in the packet range is
1358         available, see <xref linkend="ChIOPacketRangeSection"/>.
1359     </para>
1360     <para>
1361         There are three functions to manipulate the marked state of a packet:
1362         <itemizedlist>
1363                 <listitem>
1364                 <para>
1365                         <command>Mark packet (toggle)</command> toggles the marked state
1366                         of a single packet.
1367                 </para>
1368                 </listitem>
1369                 <listitem>
1370                 <para>
1371                         <command>Mark all packets</command> set the mark state of all
1372                         packets.
1373                 </para>
1374                 </listitem>
1375                 <listitem>
1376                 <para>
1377                         <command>Unmark all packets</command> reset the mark state of all
1378                         packets.
1379                 </para>
1380                 </listitem>
1381         </itemizedlist>
1382         These mark function are available from the "Edit" menu, and the
1383         "Mark packet (toggle)" function is also available from the pop-up menu of
1384         the "Packet List" pane.
1385     </para>
1386   </section>
1387
1388   <section id="ChWorkTimeFormatsSection"><title>Time display formats and time
1389   references</title>
1390         <para>
1391         While packets are captured, each packet is timestamped. These timestamps
1392         will be saved to the capture file, so they will be available for later
1393         analysis.
1394         </para>
1395         <para>
1396         A detailed description of timestamps, timezones and alike can be found at: <xref
1397                 linkend="ChAdvTimestamps"/>.
1398         </para>
1399         <para>
1400         The timestamp presentation format and the precision in the packet list can
1401         be chosen using the View menu, see <xref linkend="ChUseWiresharkViewMenu"/>.
1402         </para>
1403         <para>
1404         The available presentation formats are:
1405         <itemizedlist>
1406         <listitem><para><command>Date and Time of Day:  1970-01-01 01:02:03.123456</command>
1407                 The absolute date and time of the day when the packet was captured.</para>
1408         </listitem>
1409         <listitem><para><command>Time of Day:  01:02:03.123456</command>
1410                 The absolute time of the day when the packet was captured.</para>
1411         </listitem>
1412         <listitem><para><command>Seconds Since Beginning of Capture:  123.123456</command>
1413                 The time relative to the start of the capture file or the first
1414                 "Time Reference" before this packet (see <xref
1415                 linkend="ChWorkTimeReferencePacketSection"/>).</para>
1416         </listitem>
1417         <listitem><para><command>Seconds Since Previous Captured Packet:  1.123456</command>
1418                 The time relative to the previous captured packet.</para>
1419         </listitem>
1420         <listitem><para><command>Seconds Since Previous Displayed Packet:  1.123456</command>
1421                 The time relative to the previous displayed packet.</para>
1422         </listitem>
1423         </itemizedlist>
1424         </para>
1425         <para>
1426         The available precisions (aka. the number of displayed decimal places) are:
1427         <itemizedlist>
1428         <listitem><para><command>Automatic</command>
1429         The timestamp precision of
1430         the loaded capture file format will be used (the default).</para>
1431         </listitem>
1432         <listitem><para><command>Seconds, Deciseconds, Centiseconds, Milliseconds,
1433         Microseconds or Nanoseconds</command>
1434         The timestamp precision will be forced to the given setting. If the
1435         actually available
1436         precision is smaller, zeros will be appended. If the precision is larger,
1437         the remaining decimal places will be cut off.</para>
1438         </listitem>
1439         </itemizedlist>
1440         </para>
1441         <para>
1442         Precision example: If you have a timestamp and it's displayed using,
1443         "Seconds Since Previous Packet", : the value might be 1.123456. This will
1444         be displayed using the "Automatic" setting for libpcap files (which is
1445         microseconds). If you use Seconds it would show simply 1 and if you use
1446         Nanoseconds it shows 1.123456000.
1447         </para>
1448   <section id="ChWorkTimeReferencePacketSection">
1449   <title>Packet time referencing</title>
1450     <para>
1451         The user can set time references to packets. A time reference is the
1452         starting point for all subsequent packet time calculations. It will be
1453         useful, if you want to see the time values relative to a special packet,
1454         e.g. the start of a new request. It's possible to set multiple time
1455         references in the capture file.
1456     </para>
1457     <warning><title>Warning!</title>
1458     <para>
1459         The time references will not be saved permanently and will be lost when
1460         you close the capture file.
1461         </para>
1462     </warning>
1463     <note><title>Note!</title>
1464     <para>
1465         Time referencing will only be useful, if the time display format is set to
1466         "Seconds Since Beginning of Capture". If one of the other time display
1467         formats are used, time referencing will have no effect (and will make no
1468         sense either).
1469         </para>
1470     </note>
1471     <para>
1472         To work with time references, choose one of the "Time Reference" items
1473         in the "Edit" menu , see <xref linkend="ChUseEditMenuSection"/>, or from
1474         the pop-up menu of the "Packet List" pane.
1475         </para>
1476         <itemizedlist>
1477         <listitem><para><command>Set Time Reference (toggle)</command>
1478                 Toggles the time reference state of the currently selected
1479                 packet to on or off.</para>
1480         </listitem>
1481         <listitem><para><command>Find Next</command>
1482                 Find the next time referenced packet in the "Packet List" pane.
1483                 </para>
1484         </listitem>
1485         <listitem><para><command>Find Previous</command>
1486                 Find the previous time referenced packet in the "Packet List"
1487                 pane.
1488                 </para>
1489         </listitem>
1490         </itemizedlist>
1491     <para>
1492     <figure id="ChWorkTimeReference">
1493       <title>Wireshark showing a time referenced packet</title>
1494       <graphic entityref="WiresharkTimeReference" format="PNG"/>
1495     </figure>
1496         </para>
1497         <para>
1498         A time referenced packet will be marked with the string *REF* in the Time
1499         column (see packet number 10). All subsequent packets will show the time
1500         since the last time reference.
1501         </para>
1502   </section>
1503   </section>
1504
1505 </chapter>
1506 <!-- End of WSUG Chapter Work -->
1507
1508
1509