1// WSUG Chapter Work 2 3[[ChapterWork]] 4 5== Working With Captured Packets 6 7[[ChWorkViewPacketsSection]] 8 9=== Viewing Packets You Have Captured 10 11Once you have captured some packets or you have opened a previously saved 12capture file, you can view the packets that are displayed in the packet list 13pane by simply clicking on a packet in the packet list pane, which will bring up 14the selected packet in the tree view and byte view panes. 15 16You can then expand any part of the tree to view detailed information about each 17protocol in each packet. Clicking on an item in the tree will highlight the 18corresponding bytes in the byte view. An example with a TCP packet selected is 19shown in <<ChWorkSelPack1>>. It also has the Acknowledgment number in the TCP 20header selected, which shows up in the byte view as the selected bytes. 21 22[[ChWorkSelPack1]] 23 24.Wireshark with a TCP packet selected for viewing 25image::wsug_graphics/ws-packet-selected.png[{screenshot-attrs}] 26 27You can also select and view packets the same way while Wireshark is capturing 28if you selected “Update list of packets in real time” in the “Capture 29Preferences” dialog box. 30 31In addition you can view individual packets in a separate window as shown in 32<<ChWorkPacketSepView>>. You can do this by double-clicking on an item in the 33packet list or by selecting the packet in which you are interested in the packet 34list pane and selecting menu:View[Show Packet in New Window]. This allows you to 35easily compare two or more packets, even across multiple files. 36 37[[ChWorkPacketSepView]] 38 39.Viewing a packet in a separate window 40image::wsug_graphics/ws-packet-sep-win.png[{screenshot-attrs}] 41 42Along with double-clicking the packet list and using the main menu there are a 43number of other ways to open a new packet window: 44 45- Hold down the shift key and double-click on a frame link in the packet 46 details. 47- From <<PacketListPopupMenuTable>>. 48- From <<PacketDetailsPopupMenuTable>>. 49 50[[ChWorkDisplayPopUpSection]] 51 52=== Pop-up Menus 53 54You can open a pop-up menu over the “Packet List”, its column heading, 55“Packet Details”, or “Packet Bytes” by clicking your right mouse button 56on the corresponding item. 57 58[[ChWorkColumnHeaderPopUpMenuSection]] 59 60==== Pop-up Menu Of The “Packet List” Column Header 61 62[[ChWorkColumnHeaderPopUpMenu]] 63.Pop-up menu of the “Packet List” column header 64image::wsug_graphics/ws-column-header-popup-menu.png[{screenshot-attrs}] 65 66The following table gives an overview of which functions are available 67in this header, where to find the corresponding function in the main 68menu, and a description of each item. 69 70[[ColumnHeaderPopupMenuTable]] 71.The menu items of the “Packet List” column header pop-up menu 72[options="header",cols="3,7"] 73|=== 74|Item |Description 75 76|menu:Align Left[] | 77Left-align values in this column. 78 79|menu:Align Center[] | 80Center-align values in this column. 81 82|menu:Align Right[] | 83Right-align values in this column. 84 85|menu:Column Preferences...[] | 86Open the “Preferences” dialog for this column. 87 88|menu:Edit Column[] | 89Open the column editor toolbar for this column. 90 91|menu:Resize To Contents[] | 92Resize the column to fit its values. 93 94|menu:Resolve Names[] | 95If this column contains addresses, resolve them. 96 97| _No., Time, Source, et al._ | 98Show or hide a column by selecting its item. 99 100|menu:Remove Column[] | 101Remove this column, similar to deleting it in the “Preferences” dialog. 102 103|=== 104 105[[ChWorkPacketListPanePopUpMenuSection]] 106 107==== Pop-up Menu Of The “Packet List” Pane 108 109[[ChWorkPacketListPanePopUpMenu]] 110 111.Pop-up menu of the “Packet List” pane 112image::wsug_graphics/ws-packet-pane-popup-menu.png[{screenshot-attrs}] 113 114The following table gives an overview of which functions are available 115in this pane, where to find the corresponding function in the main menu, 116and a short description of each item. 117 118[[PacketListPopupMenuTable]] 119.The menu items of the “Packet List” pop-up menu 120[options="header",cols="3,1,6"] 121|=== 122|Item |Corresponding main menu item |Description 123|menu:Mark Packet (toggle)[]|menu:Edit[]| Mark or unmark a packet. 124|menu:Ignore Packet (toggle)[]|menu:Edit[]| Ignore or inspect this packet while dissecting the capture file. 125|menu:Set Time Reference (toggle)[]|menu:Edit[]| Set or reset a time reference. 126 127|menu:Time Shift[] |menu:Edit[] | 128Opens the “Time Shift” dialog, which allows you to adjust the timestamps 129of some or all packets. 130 131|menu:Packet Comment...[] |menu:Edit[] | 132Opens the “Packet Comment” dialog, which lets you add a comment to a 133single packet. Note that the ability to save packet comments depends on 134your file format. E.g. pcapng supports comments, pcap does not. 135 136|menu:Edit Resolved Name[]|| 137Allows you to enter a name to resolve for the selected address. 138 139|menu:Apply as Filter[]|menu:Analyze[]| 140Immediately replace or append the current display filter based on the most recent packet list or packet details item selected. 141The first submenu item shows the filter and subsequent items show the different ways that the filter can be applied. 142 143|menu:Prepare as Filter[]|menu:Analyze[]| 144Change the current display filter based on the most recent packet list or packet details item selected, but don't apply it. 145The first submenu item shows the filter and subsequent items show the different ways that the filter can be changed. 146 147// XXX - add a new section describing this better. 148|menu:Conversation Filter[] || 149Apply a display filter with the address information from the selected packet. 150For example, the IP menu entry will set a filter to show the traffic between the two IP addresses of the current packet. 151 152|menu:Colorize Conversation[] || 153Create a new colorizing rule based on address information from the selected packet. 154 155|menu:SCTP[] || 156Allows you to analyze and prepare a filter for this SCTP association. 157 158|menu:Follow[TCP Stream] |menu:Analyze[] | 159Open a window that displays all the TCP segments captured that are on the same TCP connection as a selected packet. 160See <<ChAdvFollowStreamSection>>. 161 162|menu:Follow[UDP Stream] |menu:Analyze[] | 163Same functionality as “Follow TCP Stream” but for UDP “streams”. 164 165|menu:Follow[DCCP Stream] |menu:Analyze[] | 166Same functionality as “Follow TCP Stream” but for DCCP streams. 167 168|menu:Follow[TLS Stream] |menu:Analyze[] | 169Same functionality as “Follow TCP Stream” but for TLS or SSL streams. 170See the wiki page on link:{wireshark-wiki-url}SSL[SSL] for instructions 171on providing TLS keys. 172 173|menu:Follow[HTTP Stream] |menu:Analyze[] | 174Same functionality as “Follow TCP Stream” but for HTTP streams. 175 176|menu:Copy[Summary as Text] || 177Copy the summary fields as displayed to the clipboard as tab-separated 178text. 179 180|menu:Copy[...as CSV] || 181Copy the summary fields as displayed to the clipboard as comma-separated 182text. 183 184|menu:Copy[...as YAML] || 185Copy the summary fields as displayed to the clipboard as YAML data. 186 187|menu:Copy[As Filter] || 188Prepare a display filter based on the currently selected item and copy 189that filter to the clipboard. 190 191|menu:Copy[Bytes as Hex + ASCII Dump] || 192Copy the packet bytes to the clipboard in full “hexdump” format. 193 194|menu:Copy[...as Hex Dump] || 195Copy the packet bytes to the clipboard in “hexdump” format without the 196ASCII portion. 197 198|menu:Copy[...as Printable Text] || 199Copy the packet bytes to the clipboard as ASCII text, excluding 200non-printable characters. 201 202|menu:Copy[...as a Hex Stream] || 203Copy the packet bytes to the clipboard as an unpunctuated list of hex 204digits. 205 206|menu:Copy[...as Raw Binary] || 207Copy the packet bytes to the clipboard as raw binary. The data is stored 208in the clipboard using the MIME type “application/octet-stream”. 209 210|menu:Protocol Preferences[] || 211Adjust the preferences for the selected protocol. 212 213|menu:Decode As...[] |menu:Analyze[] | 214Change or apply a new relation between two dissectors. 215 216|menu:Show Packet in New Window[] |menu:View[] | 217Shows the selected packet in a separate window. The separate window 218shows only the packet details and bytes. See <<ChWorkPacketSepView>> for 219details. 220 221|=== 222 223 224[[ChWorkPacketDetailsPanePopUpMenuSection]] 225 226==== Pop-up Menu Of The “Packet Details” Pane 227 228[[ChWorkPacketDetailsPanePopUpMenu]] 229 230.Pop-up menu of the “Packet Details” pane 231image::wsug_graphics/ws-details-pane-popup-menu.png[{screenshot-attrs}] 232 233The following table gives an overview of which functions are available in this 234pane, where to find the corresponding function in the main menu, and a short 235description of each item. 236 237[[PacketDetailsPopupMenuTable]] 238 239.The menu items of the “Packet Details” pop-up menu 240[options="header",cols="3,1,6"] 241|=== 242|Item |Corresponding main menu item |Description 243|menu:Expand Subtrees[]|menu:View[]| Expand the currently selected subtree. 244|menu:Collapse Subtrees[]|menu:View[]| Collapse the currently selected subtree. 245|menu:Expand All[]|menu:View[]| Expand all subtrees in all packets in the capture. 246|menu:Collapse All[]|menu:View[]| Wireshark keeps a list of all the protocol subtrees that are expanded, and uses it to ensure that the correct subtrees are expanded when you display a packet. This menu item collapses the tree view of all packets in the capture list. 247|menu:Apply as Column[]|| Use the selected protocol item to create a new column in the packet list. 248 249|menu:Apply as Filter[]|menu:Analyze[]| 250Immediately replace or append the current display filter based on the most recent packet list or packet details item selected. 251The first submenu item shows the filter and subsequent items show the different ways that the filter can be applied. 252 253|menu:Prepare as Filter[]|menu:Analyze[]| 254Change the current display filter based on the most recent packet list or packet details item selected, but don't apply it. 255The first submenu item shows the filter and subsequent items show the different ways that the filter can be changed. 256 257|menu:Colorize with Filter[]|| This menu item uses a display filter with the information from the selected protocol item to build a new colorizing rule. 258 259|menu:Follow[TCP Stream] |menu:Analyze[] | 260Open a window that displays all the TCP segments captured that are on the same TCP connection as a selected packet. 261See <<ChAdvFollowStreamSection>>. 262 263|menu:Follow[UDP Stream] |menu:Analyze[] | 264Same functionality as “Follow TCP Stream” but for UDP “streams”. 265 266|menu:Follow[TLS Stream] |menu:Analyze[] | 267Same functionality as “Follow TCP Stream” but for TLS or SSL streams. 268See the wiki page on link:{wireshark-wiki-url}SSL[SSL] for instructions 269on providing TLS keys. 270 271|menu:Follow[HTTP Stream] |menu:Analyze[] | 272Same functionality as “Follow TCP Stream” but for HTTP streams. 273 274|menu:Copy[All Visible Items] |menu:Edit[] | 275Copy the packet details as displayed. 276 277|menu:Copy[All Visible Selected Tree Items] |menu:Edit[] | 278Copy the selected packet detail and its children as displayed. 279 280|menu:Copy[Description] |menu:Edit[] | 281Copy the displayed text of the selected field to the system clipboard. 282 283|menu:Copy[Fieldname] |menu:Edit[] | 284Copy the name of the selected field to the system clipboard. 285 286|menu:Copy[Value] |menu:Edit[] | 287Copy the value of the selected field to the system clipboard. 288 289|menu:Copy[As Filter]| menu:Edit[] | 290Prepare a display filter based on the currently selected item and copy 291it to the clipboard. 292 293|menu:Copy[Bytes as Hex + ASCII Dump] || 294Copy the packet bytes to the clipboard in full “hexdump” format. 295 296|menu:Copy[...as Hex Dump] || 297Copy the packet bytes to the clipboard in “hexdump” format without the 298ASCII portion. 299 300|menu:Copy[...as Printable Text] || 301Copy the packet bytes to the clipboard as ASCII text, excluding 302non-printable characters. 303 304|menu:Copy[...as a Hex Stream] || 305Copy the packet bytes to the clipboard as an unpunctuated list of hex 306digits. 307 308|menu:Copy[...as Raw Binary] || 309Copy the packet bytes to the clipboard as raw binary. The data is stored 310in the clipboard using the MIME type “application/octet-stream”. 311 312|menu:Copy[...as Escaped String] || 313Copy the packet bytes to the clipboard as C-style escape sequences. 314 315|menu:Export Packet Bytes...[] |menu:File[] | 316This menu item is the same as the File menu item of the same name. It 317allows you to export raw packet bytes to a binary file. 318 319|menu:Wiki Protocol Page[]|| Show the wiki page corresponding to the currently selected protocol in your web browser. 320|menu:Filter Field Reference[]|| Show the filter field reference web page corresponding to the currently selected protocol in your web browser. 321 322|menu:Protocol Preferences[] || 323Adjust the preferences for the selected protocol. 324 325|menu:Decode As...[]|menu:Analyze[]| Change or apply a new relation between two dissectors. 326 327|menu:Go to Linked Packet[] |menu:Go[] | 328If the selected field has a corresponding packet such as the matching 329request for a DNS response, go to it. 330 331|menu:Show Linked Packet in New Window[] |menu:Go[] | 332If the selected field has a corresponding packet such as the matching 333request for a DNS response, show the selected packet in a separate 334window. See <<ChWorkPacketSepView>> for details. 335 336|=== 337 338[[ChWorkPacketBytesPanePopUpMenuSection]] 339 340==== Pop-up Menu Of The “Packet Bytes” Pane 341 342[[ChWorkPacketBytesPanePopUpMenu]] 343 344.Pop-up menu of the “Packet Bytes” pane 345image::wsug_graphics/ws-bytes-pane-popup-menu.png[{screenshot-attrs}] 346 347The following table gives an overview of which functions are available 348in this pane along with a short description of each item. 349 350[[PacketBytesPopupMenuTable]] 351 352.The menu items of the “Packet Bytes” pop-up menu 353[options="header",cols="3,7"] 354|=== 355|Item |Description 356 357|menu:Copy Bytes as Hex + ASCII Dump[] | 358Copy the packet bytes to the clipboard in full “hexdump” format. 359 360|menu:...as Hex Dump[] | 361Copy the packet bytes to the clipboard in “hexdump” format without the 362ASCII portion. 363 364|menu:...as Printable Text[] | 365Copy the packet bytes to the clipboard as ASCII text, excluding 366non-printable characters. 367 368|menu:...as a Hex Stream[] | 369Copy the packet bytes to the clipboard as an unpunctuated list of hex 370digits. 371 372|menu:...as Raw Binary[] | 373Copy the packet bytes to the clipboard as raw binary. The data is stored 374in the clipboard using the MIME type “application/octet-stream”. 375 376|menu:...as Escaped String[] | 377Copy the packet bytes to the clipboard as C-style escape sequences. 378 379|menu:Show bytes as hexadecimal[] | 380Display the byte data as hexadecimal digits. 381 382|menu:Show bytes as bits[] | 383Display the byte data as binary digits. 384 385|menu:Show text based on packet[] | 386Show the “hexdump” data with text. 387 388|menu:...as ASCII[] | 389Use ASCII encoding when displaying “hexdump” text. 390 391|menu:...as EBCDIC[] | 392Use EBCDIC encoding when displaying “hexdump” text. 393 394|=== 395 396[[ChWorkDisplayFilterSection]] 397 398=== Filtering Packets While Viewing 399 400Wireshark has two filtering languages: _capture filters_ and _display filters_. 401_Capture filters_ are used for filtering 402when capturing packets and are discussed in <<ChCapCaptureFilterSection>>. 403_Display filters_ are used for filtering 404which packets are displayed and are discussed below. 405 406Display filters allow you to concentrate on the packets you are interested in 407while hiding the currently uninteresting ones. They allow you to only display packets 408based on: 409 410* Protocol 411 412* The presence of a field 413 414* The values of fields 415 416* A comparison between fields 417 418* ... and a lot more! 419 420To only display packets containing a particular protocol, type the protocol name 421in the display filter toolbar of the Wireshark 422window and press enter to apply the filter. <<ChWorkTCPFilter>> shows an 423example of what happens when you type _tcp_ in the display filter toolbar. 424 425[NOTE] 426==== 427Protocol and field names are usually in lowercase. 428==== 429 430[NOTE] 431==== 432Don’t forget to press enter or click on the apply display filter button after entering the filter 433expression. 434==== 435 436 437[[ChWorkTCPFilter]] 438 439.Filtering on the TCP protocol 440image::wsug_graphics/ws-display-filter-tcp.png[{screenshot-attrs}] 441 442As you may have noticed, only packets containing the TCP protocol are now displayed, 443so packets 1-10 are hidden and packet number 11 444is the first packet displayed. 445 446[NOTE] 447==== 448When using a display filter, all packets remain in the capture file. The display 449filter only changes the display of the capture file but not its content! 450==== 451 452To remove the filter, click on the btn:[Clear] button to the right of the 453display filter field. All packets will become visible again. 454 455Display filters can be very powerful and are discussed in further detail in 456<<ChWorkBuildDisplayFilterSection>> 457 458It's also possible to create display filters with the 459_Display Filter Expression_ dialog box. More information about 460the _Display Filter Expression_ dialog box is available in 461<<ChWorkFilterAddExpressionSection>>. 462 463 464[[ChWorkBuildDisplayFilterSection]] 465 466=== Building Display Filter Expressions 467 468Wireshark provides a display filter language that enables you 469to precisely control which packets are displayed. They can be used 470to check for the presence of a protocol or field, the value of a field, or 471even compare two fields to each other. These comparisons can be combined 472with logical operators, like "and" and "or", and parentheses 473into complex expressions. 474 475The following sections will go into the display filter functionality in 476more detail. 477 478[TIP] 479==== 480There are many display filter examples on the _Wireshark Wiki Display 481Filter page_ at: link:{wireshark-wiki-url}DisplayFilters[]. 482==== 483 484==== Display Filter Fields 485 486The simplest display filter is one that displays a single protocol. 487To only display packets containing a particular protocol, type the protocol 488into Wireshark's display filter toolbar. For example, to only 489display TCP packets, type _tcp_ into Wireshark's display filter toolbar. 490Similarly, to only display 491packets containing a particular field, type the field 492into Wireshark's display filter toolbar. For example, to only display 493HTTP requests, type _http.request_ into Wireshark's display filter toolbar. 494 495You can filter on any protocol that Wireshark supports. You can 496also filter on any field that a dissector adds to the tree view, if the dissector 497has added an abbreviation for that field. A full list of the available protocols 498and fields is available through the menu item 499menu:View[Internals,Supported Protocols]. 500 501// XXX - add some more info here and a link to the statusbar info. 502 503==== Comparing Values 504 505You can build display filters that compare values using a number of different 506comparison operators. For example, to only display packets to or 507from the IP address 192.168.0.1, use `ip.addr==192.168.0.1`. 508 509A complete list of available comparison operators is shown in <<DispCompOps>>. 510 511[TIP] 512==== 513English and C-like operators are interchangeable and can be mixed within a filter string. 514==== 515 516[[DispCompOps]] 517 518.Display Filter comparison operators 519[options="header",cols="1,1,1,4"] 520|=== 521|English|C-like|Description|Example 522|eq |== |Equal| `ip.src==10.0.0.5` 523|ne |!= |Not equal| `ip.src!=10.0.0.5` 524|gt |> |Greater than| `frame.len > 10` 525|lt |< |Less than| `frame.len < 128` 526|ge |>= |Greater than or equal to| `frame.len ge 0x100` 527|le |\<= |Less than or equal to| `frame.len \<= 0x20` 528|contains||Protocol, field or slice contains a value| `sip.To contains "a1762"` 529|matches|~|Protocol or text field matches a Perl-compatible regular expression| `http.host matches "acme\\.(org\|com\|net)"` 530|bitwise_and|&|Bitwise AND is non-zero| `tcp.flags & 0x02` 531|=== 532 533All protocol fields have a type. <<ChWorkFieldTypes>> provides a list 534of the types with examples of how to use them in display filters. 535 536[[ChWorkFieldTypes]] 537 538===== Display Filter Field Types 539 540Unsigned integer:: 541 Can be 8, 16, 24, 32, or 64 bits. You can express integers in decimal, octal, 542 or hexadecimal. The following display filters are equivalent: 543+ 544`ip.len le 1500` 545+ 546`ip.len le 02734` 547+ 548`ip.len le 0x5dc` 549 550Signed integer:: 551 Can be 8, 16, 24, 32, or 64 bits. As with unsigned integers you can use 552 decimal, octal, or hexadecimal. 553 554Boolean:: 555 Can be 1 (for true), or 0 (for false). 556+ 557A Boolean field is present whether its value is true or false. For example, 558`tcp.flags.syn` is present in all TCP packets containing the flag, whether 559the SYN flag is 0 or 1. To only match TCP packets with the SYN flag set, you need 560to use `tcp.flags.syn == 1`. 561 562Ethernet address:: 563 6 bytes separated by a colon (:), dot (.), or dash (-) with one or two bytes between separators: 564+ 565`eth.dst == ff:ff:ff:ff:ff:ff` 566+ 567`eth.dst == ff-ff-ff-ff-ff-ff` 568+ 569`eth.dst == ffff.ffff.ffff` 570 571IPv4 address:: 572 `ip.addr == 192.168.0.1` 573+ 574Classless InterDomain Routing (CIDR) notation can be used to test if 575an IPv4 address is in a certain subnet. For example, this display 576filter will find all packets in the 129.111 Class-B network: 577+ 578`ip.addr == 129.111.0.0/16` 579 580IPv6 address:: 581 `ipv6.addr == ::1` 582+ 583As with IPv4 addresses, IPv6 addresses can match a subnet. 584 585Text string:: 586 `http.request.uri == "https://www.wireshark.org/"` 587+ 588Strings are a sequence of bytes. Functions like `lower()` use ASCII, otherwise 589no particular encoding is assumed. String literals are specified with double 590quotes. Characters can also be specified using a byte escape sequence using 591hex \x__hh__ or octal {backslash}__ddd__, where _h_ and _d_ are hex and octal 592numerical digits respectively: 593+ 594`dns.qry.name contains "www.\x77\x69\x72\x65\x73\x68\x61\x72\x6b.org"` 595+ 596Alternatively a raw string syntax can be used. Such strings are prefixed with `r` or `R` and treat 597backslash as a literal character. 598+ 599`http.user_agent matches r"\(X11;"` 600 601Date and time:: 602`frame.time == "Sep 26, 2004 23:18:04.954975"` 603+ 604`ntp.xmt ge "2020-07-04 12:34:56"` 605+ 606The value of an absolute time field is expressed as a string, using one of the 607two formats above. Fractional seconds can be omitted or specified up to 608nanosecond precision; extra trailing zeros are allowed but not other digits. 609The string cannot take a time zone suffix, and is always parsed as in the local 610time zone, even for fields that are displayed in UTC. 611+ 612In the first format, the abbreviated month names must be in English regardless 613of locale. In the second format, any number of time fields may be omitted, in 614the order from least significant (seconds) to most, but at least the entire 615date must be specified: 616+ 617`frame.time < "2022-01-01"` 618+ 619In the second format, a `T` may appear between the date and time as in 620ISO 8601, but not when less significant times are dropped. 621 622[[ChWorkFilterExamples]] 623 624===== Some Examples 625 626---- 627udp contains 81:60:03 628---- 629The display filter above matches packets that contains the 3-byte sequence 0x81, 0x60, 6300x03 anywhere in the UDP header or payload. 631---- 632sip.To contains "a1762" 633---- 634The display filter above matches packets where the SIP To-header contains the string "a1762" 635anywhere in the header. 636---- 637http.host matches "acme\\.(org|com|net)" 638---- 639The display filter above matches HTTP packets where the HOST header contains 640acme.org, acme.com, or acme.net. 641Comparisons are case-insensitive. 642---- 643tcp.flags & 0x02 644---- 645That display filter will match all packets that contain the “tcp.flags” field with the 0x02 bit, 646i.e. the SYN bit, set. 647 648==== Possible Pitfalls Using Regular Expressions 649 650String literals containing regular expressions are parsed twice. Once by Wireshark's display 651filter engine and again by the PCRE library. It's important to keep this in mind when using 652the "matches" operator with regex escape sequences and special characters. 653 654For example the filter expression `+frame matches "AB\x43"+` uses the string `+"ABC"+` as input 655pattern to PCRE. However the expression `+frame matches "AB\\x43"+` uses the string `+"AB\x43"+` 656as the pattern. In this case both expressions give the same result because Wireshark and PCRE 657both support the same byte escape sequence (0x43 is the ASCII hex code for `C`). 658 659An example where this fails badly is `+foo matches "bar\x28"+`. Because 0x28 is the ASCII 660code for `(` the pattern input to PCRE is `+"bar("+`. This regular expression is syntactically 661invalid (missing closing parenthesis). To match a literal parenthesis in a display filter regular 662expression it must be escaped (twice) with backslashes. 663 664Another common pitfall is using `\.` instead of `\\.` in a regular expression. The former 665will match any character (the backslash is superfluous) while the latter will match a literal dot. 666 667TIP: Using raw strings avoids most problem with the "matches" operator and double escapes. 668 669==== Combining Expressions 670 671You can combine filter expressions in Wireshark using the logical operators shown in <<FiltLogOps>> 672 673[[FiltLogOps]] 674 675.Display Filter Logical Operations 676[options="header",cols="1,1,1,4"] 677|=== 678|English |C-like |Description | Example 679|and |&&| Logical AND | `ip.src==10.0.0.5 and tcp.flags.fin` 680|or |\|\| | Logical OR | `ip.src==10.0.0.5 or ip.src==192.1.1.1` 681|xor |^^ | Logical XOR | `tr.dst[0:3] == 0.6.29 xor tr.src[0:3] == 0.6.29` 682|not |! | Logical NOT | `not llc` 683|[...] | | Subsequence | See “Slice Operator” below. 684|in | | Set Membership| http.request.method in {"HEAD", "GET"}. See “Membership Operator” below. 685|=== 686 687==== Slice Operator 688Wireshark allows you to select a subsequence of a sequence in rather elaborate 689ways. After a label you can place a pair of brackets [] containing a comma 690separated list of range specifiers. 691---- 692eth.src[0:3] == 00:00:83 693---- 694The example above uses the n:m format to specify a single range. In this case n 695is the beginning offset and m is the length of the range being specified. 696---- 697eth.src[1-2] == 00:83 698---- 699The example above uses the n-m format to specify a single range. In this case n 700is the beginning offset and m is the ending offset. 701---- 702eth.src[:4] == 00:00:83:00 703---- 704The example above uses the :m format, which takes everything from the beginning 705of a sequence to offset m. It is equivalent to 0:m 706---- 707eth.src[4:] == 20:20 708---- 709The example above uses the n: format, which takes everything from offset n to 710the end of the sequence. 711---- 712eth.src[2] == 83 713---- 714The example above uses the n format to specify a single range. In this case the 715element in the sequence at offset n is selected. This is equivalent to n:1. 716---- 717eth.src[0:3,1-2,:4,4:,2] == 71800:00:83:00:83:00:00:83:00:20:20:83 719---- 720Wireshark allows you to string together single ranges in a comma separated list 721to form compound ranges as shown above. 722 723==== Membership Operator 724Wireshark allows you to test a field for membership in a set of values or 725fields. After the field name, use the `in` operator followed by the set items 726surrounded by braces {}. For example, to display packets with a TCP source or 727destination port of 80, 443, or 8080, you can use `tcp.port in {80, 443, 8080}`. 728Set elements must be separated by commas. 729The set of values can also contain ranges: `tcp.port in {443,4430..4434}`. 730 731[NOTE] 732==== 733The display filter 734---- 735tcp.port in {80, 443, 8080} 736---- 737is equivalent to 738---- 739tcp.port == 80 || tcp.port == 443 || tcp.port == 8080 740---- 741However, the display filter 742---- 743tcp.port in {443, 4430..4434} 744---- 745is not equivalent to 746---- 747tcp.port == 443 || (tcp.port >= 4430 && tcp.port <= 4434) 748---- 749This is because comparison operators are satisfied when _any_ field 750matches the filter, so a packet with a source port of 56789 and 751destination port of port 80 would also match the second filter 752since `56789 >= 4430 && 80 \<= 4434` is true. In contrast, the 753membership operator tests a single field against the range condition. 754==== 755 756 757 758Sets are not just limited to numbers, other types can be used as well: 759---- 760http.request.method in {"HEAD", "GET"} 761ip.addr in {10.0.0.5 .. 10.0.0.9, 192.168.1.1..192.168.1.9} 762frame.time_delta in {10 .. 10.5} 763---- 764 765==== Functions 766 767The display filter language has a number of functions to convert fields, see 768<<DispFunctions>>. 769 770[[DispFunctions]] 771.Display Filter Functions 772[options="header",cols="1,4"] 773|=== 774|Function|Description 775|upper |Converts a string field to uppercase. 776|lower |Converts a string field to lowercase. 777|len |Returns the byte length of a string or bytes field. 778|count |Returns the number of field occurrences in a frame. 779|string |Converts a non-string field to a string. 780|=== 781 782The `upper` and `lower` functions can used to force case-insensitive matches: 783`lower(http.server) contains "apache"`. 784 785To find HTTP requests with long request URIs: `len(http.request.uri) > 100`. 786Note that the `len` function yields the string length in bytes rather than 787(multi-byte) characters. 788 789Usually an IP frame has only two addresses (source and destination), but in case 790of ICMP errors or tunneling, a single packet might contain even more addresses. 791These packets can be found with `count(ip.addr) > 2`. 792 793The `string` function converts a field value to a string, suitable for use with operators 794like "matches" or "contains". Integer fields are converted to their decimal representation. 795It can be used with IP/Ethernet addresses (as well as others), but not with string or 796byte fields. 797 798For example, to match odd frame numbers: 799---- 800string(frame.number) matches "[13579]$" 801---- 802 803To match IP addresses ending in 255 in a block of subnets (172.16 to 172.31): 804---- 805string(ip.dst) matches r"^172\.(1[6-9]|2[0-9]|3[0-1])\.[0-9]{1,3}\.255" 806---- 807 808[[ChWorkBuildDisplayFilterTransitional]] 809 810==== Sometimes Fields Change Names 811 812As protocols evolve they sometimes change names or are superseded by 813newer standards. For example, DHCP extends and has largely replaced 814BOOTP and TLS has replaced SSL. If a protocol dissector originally used 815the older names and fields for a protocol the Wireshark development team 816might update it to use the newer names and fields. In such cases they 817will add an alias from the old protocol name to the new one in order to 818make the transition easier. 819 820For example, the DHCP dissector was originally developed for the BOOTP 821protocol but as of Wireshark 3.0 all of the “bootp” display filter 822fields have been renamed to their “dhcp” equivalents. You can still use 823the old filter names for the time being, e.g. “bootp.type” is equivalent 824to “dhcp.type” but Wireshark will show the warning “"bootp" is deprecated” 825when you use it. Support for the deprecated fields may be removed in the future. 826 827[[ChWorkFilterAddExpressionSection]] 828 829=== The “Display Filter Expression” Dialog Box 830 831When you are accustomed to Wireshark’s filtering system and know what labels you 832wish to use in your filters it can be very quick to simply type a filter string. 833However if you are new to Wireshark or are working with a slightly unfamiliar 834protocol it can be very confusing to try to figure out what to type. The 835“Display Filter Expression” dialog box helps with this. 836 837[TIP] 838==== 839The “Display Filter Expression” dialog box is an excellent way to learn how to write 840Wireshark display filter strings. 841==== 842 843 844[[ChWorkFilterAddExpression1]] 845 846.The “Display Filter Expression” dialog box 847image::wsug_graphics/ws-filter-add-expression.png[{screenshot-attrs}] 848// Screenshot from Wireshark 3.1.1 849 850When you first bring up the Display Filter Expression dialog box you are shown a tree 851of field names, organized by protocol, and a box for selecting a relation. 852 853Field Name:: 854Select a protocol field from the protocol field tree. Every protocol with 855filterable fields is listed at the top level. You can search for a particular 856protocol entry by entering the first few letters of the protocol name. By 857expanding a protocol name you can get a list of the field names available for 858filtering for that protocol. 859 860Relation:: 861Select a relation from the list of available relation. The _is present_ is a 862unary relation which is true if the selected field is present in a packet. All 863other listed relations are binary relations which require additional data (e.g. 864a _Value_ to match) to complete. 865+ 866When you select a field from the field name list and select a binary relation 867(such as the equality relation ==) you will be given the opportunity to enter a 868value, and possibly some range information. 869 870Value:: 871You may enter an appropriate value in the _Value_ text box. The _Value_ will 872also indicate the type of value for the _Field Name_ you have selected (like 873character string). 874 875Predefined Values:: 876Some of the protocol fields have predefined values available, much like enumerations 877in C. If the selected protocol field has such values defined, you can choose one 878of them here. 879 880Search:: 881Lets you search for a full or partial field name or description. 882Regular expressions are supported. 883For example, searching for “tcp.*flag” shows the TCP flags fields supported by a wide variety of dissectors, while “^tcp.flag” shows only the TCP flags fields supported by the TCP dissector. 884 885Range:: 886A range of integers or a group of ranges, such as `1-12` or `39-42,98-2000`. 887 888btn:[Help]:: 889Opens this section of the User’s Guide. 890 891btn:[OK]:: 892When you have built a satisfactory expression click btn:[OK] and a filter string 893will be built for you. 894 895btn:[Cancel]:: 896You can leave the “Add Expression...” dialog box without any effect by 897clicking the btn:[Cancel] button. 898 899[[ChWorkDefineFilterSection]] 900 901=== Defining And Saving Filters 902 903You create pre-defined filters that appear in the capture and display filter bookmark menus (image:wsug_graphics/toolbar/filter-toolbar-bookmark.png[height=16,width=12]). 904This can save time in remembering and retyping some of the more complex filters you use. 905 906To create or edit capture filters, select menu:Manage Capture Filters[] from the capture filter bookmark menu or menu:Capture[Capture Filters...] from the main menu. 907Display filters can be created or edited by selecting menu:Manage Display Filters[] from the display filter bookmark menu or menu:Analyze[Display Filters...] from the main menu. 908Wireshark will open the corresponding dialog as shown in <<FiltersDialog>>. 909The two dialogs look and work similar to one another. 910Both are described here, and the differences are noted as needed. 911 912[[FiltersDialog]] 913 914.The “Capture Filters” and “Display Filters” dialog boxes 915image::wsug_graphics/ws-filters.png[{screenshot-attrs}] 916 917btn:[{plus}]:: 918Adds a new filter to the list. 919You can edit the filter name or expression by double-clicking on it. 920+ 921The filter name is used in this dialog to identify the filter for your convenience and is not used elsewhere. 922You can create multiple filters with the same name, but this is not very useful. 923+ 924When typing in a filter string, the background color will change depending on the validity of the filter similar to the main capture and display filter toolbars. 925 926btn:[-]:: 927Delete the selected filter. 928This will be greyed out if no filter is selected. 929 930// XXX Asciidoctor doesn't seem to allow images in DL terms, otherwise we could use 931// list-copy.template.png here. 932btn:[Copy]:: 933Copy the selected filter. 934This will be greyed out if no filter is selected. 935 936btn:[OK]:: 937Saves the filter settings and closes the dialog. 938 939btn:[Cancel]:: 940Closes the dialog without saving any changes. 941 942[[ChWorkDefineFilterMacrosSection]] 943 944=== Defining And Saving Filter Macros 945 946You can define a filter macro with Wireshark and label it for later use. 947This can save time in remembering and retyping some of the more complex filters 948you use. 949 950To define and save your own filter macros, follow the steps below: 951 952. In the main menu select menu:Analyze[Display Filter Macros...]. Wireshark will open a corresponding dialog <<FilterMacrosDialog>>. 953+ 954[[FilterMacrosDialog]] 955+ 956.Display Filter Macros window 957image::wsug_graphics/ws-filter-macros.png[{screenshot-attrs}] 958 959. To add a new filter macro, click the btn:[{plus}] button in the bottom-left corner. A new row will appear in the Display Filter Macros table above. 960 961. Enter the name of your macro in the `Name` column. Enter your filter macro in the `Text` column. 962 963. To save your modifications, click the btn:[OK] button in the bottom-right corner of the <<FilterMacrosDialog>>. 964 965To learn more about display filter macro syntax, see <<ChDisplayFilterMacrosSection>>. 966 967[[ChWorkFindPacketSection]] 968 969=== Finding Packets 970 971You can easily find packets once you have captured some packets or have 972read in a previously saved capture file. Simply select menu:Edit[Find 973Packet...] in the main menu. Wireshark will open a toolbar between the 974main toolbar and the packet list shown in <<ChWorkFindPacketToolbar>>. 975 976==== The “Find Packet” Toolbar 977 978[[ChWorkFindPacketToolbar]] 979 980.The “Find Packet” toolbar 981image::wsug_graphics/ws-find-packet.png[{screenshot-attrs}] 982 983You can search using the following criteria: 984 985Display filter:: 986 Enter a display filter string into the text entry field and click the btn:[Find] button. 987 + 988 For example, to find the three way handshake for a connection from host 192.168.0.1, use the following filter string: 989+ 990---- 991ip.src==192.168.0.1 and tcp.flags.syn==1 992---- 993+ 994The value to be found will be syntax checked while you type it in. If 995the syntax check of your value succeeds, the background of the entry 996field will turn green, if it fails, it will turn red. For more details 997see <<ChWorkDisplayFilterSection>> 998 999Hexadecimal Value:: 1000 Search for a specific byte sequence in the packet data. 1001+ 1002For example, use “ef:bb:bf” to find the next packet that contains the 1003link:{wikipedia-main-url}Byte_order_mark[UTF-8 byte order mark]. 1004 1005String:: 1006 Find a string in the packet data, with various options. 1007 1008Regular Expression:: 1009 Search the packet data using link:{pcre2pattern-url}[Perl-compatible 1010 regular expressions]. PCRE patterns are beyond the scope of this 1011 document, but typing “pcre test” into your favorite search engine 1012 should return a number of sites that will help you test and explore 1013 your expressions. 1014 1015[[ChWorkGoToPacketSection]] 1016 1017=== Go To A Specific Packet 1018 1019You can easily jump to specific packets with one of the menu items in 1020the menu:Go[] menu. 1021 1022==== The “Go Back” Command 1023 1024Go back in the packet history, works much like the page history in most 1025web browsers. 1026 1027==== The “Go Forward” Command 1028 1029Go forward in the packet history, works much like the page history in 1030most web browsers. 1031 1032==== The “Go to Packet” Toolbar 1033 1034[[ChWorkGoToPacketToolbar]] 1035 1036.The “Go To Packet” toolbar 1037image::wsug_graphics/ws-goto-packet.png[{screenshot-attrs}] 1038 1039This toolbar can be opened by selecting menu:Go[Go to packet...] from 1040the main menu. It appears between the main toolbar and the packet list, 1041similar to the <<ChWorkFindPacketToolbar,”Find Packet” toolbar>>. 1042 1043When you enter a packet number and press btn:[Go to packet] 1044Wireshark will jump to that packet. 1045 1046==== The “Go to Corresponding Packet” Command 1047 1048If a protocol field is selected which points to another packet in the capture 1049file, this command will jump to that packet. 1050 1051As these protocol fields now work like links (just as in your Web browser), it’s 1052easier to simply double-click on the field to jump to the corresponding field. 1053 1054==== The “Go to First Packet” Command 1055 1056This command will jump to the first packet displayed. 1057 1058==== The “Go to Last Packet” Command 1059 1060This command will jump to the last packet displayed. 1061 1062[[ChWorkMarkPacketSection]] 1063 1064=== Marking Packets 1065 1066You can mark packets in the “Packet List” pane. A marked packet will be shown 1067with black background, regardless of the coloring rules set. Marking a packet 1068can be useful to find it later while analyzing in a large capture file. 1069 1070Marked packet information is not stored in the capture file or anywhere 1071else. It will be lost when the capture file is closed. 1072 1073You can use packet marking to control the output of packets when saving, 1074exporting, or printing. To do so, an option in the packet range is available, 1075see <<ChIOPacketRangeSection>>. 1076 1077There are several ways to mark and unmark packets. From the menu:Edit[] menu 1078you can select from the following: 1079 1080* menu:Mark/Unmark Packet[] toggles the marked state of a single packet. 1081 This option is also available in the packet list context menu. 1082 1083* menu:Mark All Displayed[] set the mark state of all displayed packets. 1084 1085* menu:Unmark All Displayed[] reset the mark state of all packets. 1086 1087You can also mark and unmark a packet by clicking on it in the packet list 1088with the middle mouse button. 1089 1090[[ChWorkIgnorePacketSection]] 1091 1092=== Ignoring Packets 1093 1094You can ignore packets in the “Packet List” pane. Wireshark will then 1095pretend that they not exist in the capture file. An ignored packet will 1096be shown with white background and gray foreground, regardless of the 1097coloring rules set. 1098 1099Ignored packet information is not stored in the capture file or anywhere 1100else. It will be lost when the capture file is closed. 1101 1102There are several ways to ignore and unignore packets. From the 1103menu:Edit[] menu you can select from the following: 1104 1105* menu:Ignore/Unignore Packet[] toggles the ignored state of a single 1106 packet. This option is also available in the packet list context menu. 1107 1108* menu:Ignore All Displayed[] set the ignored state of all displayed packets. 1109 1110* menu:Unignore All Displayed[] reset the ignored state of all packets. 1111 1112[[ChWorkTimeFormatsSection]] 1113 1114=== Time Display Formats And Time References 1115 1116While packets are captured, each packet is timestamped. These timestamps will be 1117saved to the capture file, so they will be available for later analysis. 1118 1119A detailed description of timestamps, timezones and alike can be found at: 1120<<ChAdvTimestamps>>. 1121 1122The timestamp presentation format and the precision in the packet list can be 1123chosen using the View menu, see <<ChUseWiresharkViewMenu>>. 1124 1125The available presentation formats are: 1126 1127* menu:Date and Time of Day: 1970-01-01 01:02:03.123456[] The absolute date and time 1128 of the day when the packet was captured. 1129 1130* menu:Time of Day: 01:02:03.123456[] The absolute time of the day when the packet 1131 was captured. 1132 1133* menu:Seconds Since Beginning of Capture: 123.123456[] The time relative to the 1134 start of the capture file or the first “Time Reference” before this packet 1135 (see <<ChWorkTimeReferencePacketSection>>). 1136 1137* menu:Seconds Since Previous Captured Packet: 1.123456[] The time relative to the 1138 previous captured packet. 1139 1140* menu:Seconds Since Previous Displayed Packet: 1.123456[] The time relative to the 1141 previous displayed packet. 1142 1143* menu:Seconds Since Epoch (1970-01-01): 1234567890.123456[] The time relative to 1144 epoch (midnight UTC of January 1, 1970). 1145 1146The available precisions (aka. the number of displayed decimal places) are: 1147 1148* menu:Automatic (from capture file)[] The timestamp precision of the loaded capture file format will be 1149 used (the default). 1150 1151* menu:Seconds[], menu:Tenths of a second[], menu:Hundredths of a second[], 1152 menu:Milliseconds[], menu:Microseconds[] or menu:Nanoseconds[] The 1153 timestamp precision will be forced to the given setting. If the 1154 actually available precision is smaller, zeros will be appended. If 1155 the precision is larger, the remaining decimal places will be cut off. 1156 1157Precision example: If you have a timestamp and it’s displayed using, “Seconds 1158Since Previous Packet” the value might be 1.123456. This will be displayed 1159using the “Automatic” setting for libpcap files (which is microseconds). If 1160you use Seconds it would show simply 1 and if you use Nanoseconds it shows 11611.123456000. 1162 1163[[ChWorkTimeReferencePacketSection]] 1164 1165==== Packet Time Referencing 1166 1167The user can set time references to packets. A time reference is the starting 1168point for all subsequent packet time calculations. It will be useful, if you 1169want to see the time values relative to a special packet, e.g. the start of a 1170new request. It’s possible to set multiple time references in the capture file. 1171 1172The time references will not be saved permanently and will be lost when you 1173close the capture file. 1174 1175Time referencing will only be useful if the time display format is set to 1176“Seconds Since Beginning of Capture”. If one of the other time display formats 1177are used, time referencing will have no effect (and will make no sense either). 1178 1179To work with time references, choose one of the menu:Time Reference[] items in 1180the menu:[Edit] menu or from the pop-up menu of the “Packet List” pane. See 1181<<ChUseEditMenuSection>>. 1182 1183* menu:Set Time Reference (toggle)[] Toggles the time reference state of the 1184 currently selected packet to on or off. 1185 1186* menu:Find Next[] Find the next time referenced packet in the “Packet List” pane. 1187 1188* menu:Find Previous[] Find the previous time referenced packet in the “Packet 1189 List” pane. 1190 1191[[ChWorkTimeReference]] 1192 1193.Wireshark showing a time referenced packet 1194image::wsug_graphics/ws-time-reference.png[{screenshot-attrs}] 1195 1196A time referenced packet will be marked with the string $$*REF*$$ in the Time 1197column (see packet number 10). All subsequent packets will show the time since 1198the last time reference. 1199 1200// End of WSUG Chapter Work 1201