1// WSUG Chapter Customizing 2 3[[ChapterCustomize]] 4 5== Customizing Wireshark 6 7[[ChCustIntroduction]] 8 9=== Introduction 10 11Wireshark’s default behaviour will usually suit your needs pretty well. However, 12as you become more familiar with Wireshark, it can be customized in various ways 13to suit your needs even better. In this chapter we explore: 14 15* How to start Wireshark with command line parameters 16 17* How to colorize the packet list 18 19* How to control protocol dissection 20 21* How to use the various preference settings 22 23[[ChCustCommandLine]] 24 25=== Start Wireshark from the command line 26 27You can start Wireshark from the command line, but it can also be started from 28most Window managers as well. In this section we will look at starting it from 29the command line. 30 31Wireshark supports a large number of command line parameters. To see what they 32are, simply enter the command _wireshark -h_ and the help information shown in 33<<ChCustEx1>> (or something similar) should be printed. 34 35[[ChCustEx1]] 36.Help information available from Wireshark 37---- 38include::wireshark-h.txt[] 39---- 40 41We will examine each of the command line options in turn. 42 43The first thing to notice is that issuing the command `wireshark` by itself will 44bring up Wireshark. However, you can include as many of the command line 45parameters as you like. Their meanings are as follows ( in alphabetical order ): 46 47// XXX - is the alphabetical order a good choice? Maybe better task based? 48 49-a <capture autostop condition>:: 50--autostop <capture autostop condition>:: 51Specify a criterion that specifies when Wireshark is to stop writing 52to a capture file. The criterion is of the form test:value, where test 53is one of: 54+ 55-- 56 duration:value:: 57 Stop writing to a capture file after value of seconds have elapsed. 58 59 filesize:value:: 60 Stop writing to a capture file after it reaches a size of value 61 kilobytes (where a kilobyte is 1000 bytes, not 1024 bytes). If 62 this option is used together with the -b option, Wireshark will 63 stop writing to the current capture file and switch to the next 64 one if filesize is reached. 65 66 files:value:: 67 Stop writing to capture files after value number of files were 68 written. 69 70 packets:value:: 71 Stop writing to a capture file after value number of packets were written. 72-- 73 74-b <capture ring buffer option>:: 75If a maximum capture file size was specified, this option causes Wireshark to 76run in “ring buffer” mode, with the specified number of files. In “ring 77buffer” mode, Wireshark will write to several capture files. Their 78name is based on the number of the file and on the creation date and 79time. 80+ 81When the first capture file fills up Wireshark will switch to writing 82to the next file, and so on. With the files option it’s 83also possible to form a “ring buffer.” This will fill up new files until the 84number of files specified, at which point the data in the first file will be 85discarded so a new file can be written. 86+ 87If the optional duration is specified, Wireshark will also 88switch to the next file when the specified number of seconds has elapsed even 89if the current file is not completely filled up. 90+ 91-- 92 duration:value:: 93 Switch to the next file after value seconds have elapsed, even 94 if the current file is not completely filled up. 95 96 filesize:value:: 97 Switch to the next file after it reaches a size of value kilobytes 98 (where a kilobyte is 1000 bytes, not 1024 bytes). 99 100 files:value:: 101 Begin again with the first file after value number of files were 102 written (form a ring buffer). 103 104 packets:value:: 105 Switch to the next file after value number of packets were written, even 106 if the current file is not completely filled up. 107 108 interval:value:: 109 Switch to the next file when the time is an exact multiple of value seconds. 110-- 111 112-B <capture buffer size>:: 113--buffer-size <capture buffer size>:: 114Set capture buffer size (in MB, default is 2MB). This is used by the capture 115driver to buffer packet data until that data can be written to disk. If you 116encounter packet drops while capturing, try to increase this size. Not supported 117on some platforms. 118 119-C <config profile>:: 120Start with the specified configuration profile. 121 122-c <capture packet count>:: 123This option specifies the maximum number of packets to capture when capturing 124live data. It would be used in conjunction with the `-k` option. 125 126--capture-comment <comment>:: 127Add the comment string to the capture file, if supported by the file format. 128 129-d <layer_type>==<selector>,<decode_as_protocol>:: 130"Decode As", see <<ChAdvDecodeAs>> for details. Example: tcp.port==8888,http 131 132-D:: 133--list-interfaces:: 134Print a list of the interfaces on which Wireshark can capture, then exit. For 135each network interface, a number and an interface name, possibly followed by a 136text description of the interface, is printed. The interface name or the number 137can be supplied to the `-i` flag to specify an interface on which to capture. 138+ 139This can be useful on systems that don’t have a command to list them (e.g., 140Windows systems, or UNIX systems lacking `ifconfig -a`). The number can be 141especially useful on Windows, where the interface name is a GUID. 142+ 143Note that “can capture” means that Wireshark was able to open that device to 144do a live capture. If, on your system, a program doing a network capture must be 145run from an account with special privileges, then, if 146Wireshark is run with the `-D` flag and is not run from such an account, it will 147not list any interfaces. 148 149--display <DISPLAY>:: 150Set the X display to use, instead of the one defined in the environment, or 151the default display. 152 153--enable-protocol <proto_name>:: 154--disable-protocol <proto_name>:: 155Enable and disable the dissection of the protocol. 156 157--enable-heuristic <short_name>:: 158--disable-heuristic <short_name>:: 159Enable and disable the dissection of the heuristic protocol. 160 161-f <capture filter>:: 162This option sets the initial capture filter expression to be used when capturing 163packets. 164 165--fullscreen:: 166Start Wireshark in full screen. 167 168-g <packet number>:: 169After reading in a capture file using the -r flag, go to the given packet 170number. 171 172-h:: 173--help:: 174This option requests Wireshark to print its version and usage instructions 175(as shown here) and exit. 176 177-H:: 178Hide the capture info dialog during live packet capture. 179 180-i <capture interface>:: 181--interface <capture interface>:: 182Set the name of the network interface or pipe to use for live packet capture. 183+ 184Network interface names should match one of the names listed in `wireshark -D` 185(described above). A number, as reported by `wireshark -D`, can also be used. If 186you’re using UNIX, `netstat -i`, `ifconfig -a` or `ip link` might also work to 187list interface names, although not all versions of UNIX support the `-a` flag to 188`ifconfig`. 189+ 190If no interface is specified, Wireshark searches the list of interfaces, 191choosing the first non-loopback interface if there are any non-loopback 192interfaces, and choosing the first loopback interface if there are no 193non-loopback interfaces; if there are no interfaces, Wireshark reports an error 194and doesn’t start the capture. 195+ 196Pipe names should be either the name of a FIFO (named pipe) or “-” to read 197data from the standard input. Data read from pipes must be in standard libpcap 198format. 199 200-J <jump filter>:: 201After reading in a capture file using the `-r` flag, jump to the first packet 202which matches the filter expression. The filter expression is in display filter 203format. If an exact match cannot be found the first packet afterwards is 204selected. 205 206-I:: 207--monitor-mode:: 208Capture wireless packets in monitor mode if available. 209 210-j:: 211Use this option after the `-J` option to search backwards for a first packet to 212go to. 213 214-k:: 215The `-k` option specifies that Wireshark should start capturing packets 216immediately. This option requires the use of the `-i` parameter to specify the 217interface that packet capture will occur from. 218 219-K <keytab file>:: 220Use the specified file for Kerberos decryption. 221 222-l:: 223This option turns on automatic scrolling if the packet list pane is being 224updated automatically as packets arrive during a capture (as specified by the 225`-S` flag). 226 227-L:: 228--list-data-link-types:: 229List the data link types supported by the interface and exit. 230 231--list-time-stamp-types:: 232List timestamp types configurable for the interface and exit. 233 234-m <font>:: 235This option sets the name of the font used for most text displayed by Wireshark. 236 237// XXX - add an example! 238 239-n:: 240Disable network object name resolution (such as hostname, TCP and UDP port 241names). 242 243-N <name resolving flags>:: 244Turns on name resolving for particular types of addresses and port numbers. The 245argument is a string that may contain the following letters: 246+ 247-- 248 N:: 249 Use external name resolver. 250 251 d:: 252 Enable name resolution from captured DNS packets. 253 254 m:: 255 Enable MAC address resolution. 256 257 n:: 258 Enable network address resolution. 259 260 t:: 261 Enable transport layer port number resolution. 262 263 v:: 264 Enable VLAN ID resolution. 265-- 266 267-o <preference or recent settings>:: 268Sets a preference or recent value, overriding the default value and any value 269read from a preference or recent file. The argument to the flag is a string of 270the form _prefname:value_, where _prefname_ is the name of the preference (which 271is the same name that would appear in the `preferences` or `recent` file), and 272_value_ is the value to which it should be set. Multiple instances of `-o 273<preference settings> ` can be given on a single command line. 274+ 275-- 276An example of setting a single preference would be: 277 278---- 279wireshark -o mgcp.display_dissect_tree:TRUE 280---- 281 282An example of setting multiple preferences would be: 283---- 284wireshark -o mgcp.display_dissect_tree:TRUE -o mgcp.udp.callagent_port:2627 285---- 286 287You can get a list of all available preference strings from the 288preferences file. See <<AppFiles>> for details. 289 290User access tables can be overridden using “uat,” followed by 291the UAT file name and a valid record for the file: 292 293---- 294wireshark -o "uat:user_dlts:\"User 0 (DLT=147)\",\"http\",\"0\",\"\",\"0\",\"\"" 295---- 296 297The example above would dissect packets with a libpcap data link type 147 as 298HTTP, just as if you had configured it in the DLT_USER protocol preferences. 299-- 300 301-p:: 302--no-promiscuous-mode:: 303Don’t put the interface into promiscuous mode. Note that the interface might be 304in promiscuous mode for some other reason. Hence, `-p` cannot be used to ensure 305that the only traffic that is captured is traffic sent to or from the machine on 306which Wireshark is running, broadcast traffic, and multicast traffic to 307addresses received by that machine. 308 309-P <path setting>:: 310Special path settings usually detected automatically. This is used for special 311cases, e.g. starting Wireshark from a known location on an USB stick. 312+ 313The criterion is of the form key:path, where key is one of: 314+ 315-- 316 persconf:path:: 317 Path of personal configuration files, like the preferences files. 318 319 persdata:path:: 320 Path of personal data files, it’s the folder initially opened. After the 321 initialization, the recent file will keep the folder last used. 322-- 323 324-r <infile>:: 325--read-file <infile>:: 326This option provides the name of a capture file for Wireshark to read and 327display. This capture file can be in one of the formats Wireshark understands. 328 329-R <read (display) filter>:: 330--read-filter <read (display) filter>:: 331This option specifies a display filter to be applied when reading packets from a 332capture file. The syntax of this filter is that of the display filters discussed 333in <<ChWorkDisplayFilterSection>>. Packets not matching the filter 334are discarded. 335 336-s <capture snapshot length>:: 337--snapshot-length <capture snapshot length>:: 338This option specifies the snapshot length to use when capturing packets. 339Wireshark will only capture _snaplen_ bytes of data for each packet. 340 341-S:: 342This option specifies that Wireshark will display packets as it captures them. 343This is done by capturing in one process and displaying them in a separate 344process. This is the same as “Update list of packets in real time” in the 345“Capture Options” dialog box. 346 347-t <time stamp format>:: 348This option sets the format of packet timestamps that are displayed in the 349packet list window. The format can be one of: 350+ 351-- 352r:: Relative, which specifies timestamps are 353displayed relative to the first packet captured. 354 355a:: Absolute, which specifies that actual times 356be displayed for all packets. 357 358ad:: Absolute with date, which specifies that 359actual dates and times be displayed for all packets. 360 361adoy:: Absolute with YYYY/DOY date, which specifies that 362actual dates and times be displayed for all packets. 363 364d:: Delta, which specifies that timestamps 365are relative to the previous packet. 366 367dd: Delta, which specifies that timestamps 368are relative to the previous displayed packet. 369 370e:: Epoch, which specifies that timestamps 371are seconds since epoch (Jan 1, 1970 00:00:00) 372 373u:: Absolute, which specifies that actual times 374be displayed for all packets in UTC. 375 376ud:: Absolute with date, which specifies that 377actual dates and times be displayed for all packets in UTC. 378 379udoy:: Absolute with YYYY/DOY date, which specifies that 380actual dates and times be displayed for all packets in UTC. 381-- 382 383-u <s | hms>:: 384Show timesamps as seconds (“s”, the default) or hours, minutes, and seconds (“hms”) 385 386-v:: 387--version:: 388This option requests Wireshark to print out its version information and 389exit. 390 391-w <savefile>:: 392This option sets the name of the file to be used to save captured packets. 393This can be '-' for stdout. 394 395-y <capture link type>:: 396--link-type <capture like types>:: 397If a capture is started from the command line with `-k`, set the data 398link type to use while capturing packets. The values reported by `-L` 399are the values that can be used. 400 401--time-stamp-type <type>:: 402If a capture is started from the command line with `-k`, set the time 403stamp type to use while capturing packets. The values reported by 404`--list-time-stamp-types` are the values that can be used. 405 406-X <eXtension option>:: 407Specify an option to be passed to a Wireshark/TShark module. The eXtension 408option is in the form extension_key:value, where extension_key can be: 409+ 410-- 411lua_script:<lua_script_filename>:: 412Tells Wireshark to load the given script in addition to the default Lua scripts. 413 414lua_script[num]:argument:: 415Tells Wireshark to pass the given argument to the lua script identified by 416_num_, which is the number indexed order of the _lua_script_ command. For 417example, if only one script was loaded with `-X lua_script:my.lua`, then `-X 418lua_script1:foo` will pass the string _foo_ to the _my.lua_ script. If two 419scripts were loaded, such as `-X lua_script:my.lua -X lua_script:other.lua` 420in that order, then a `-X lua_script2:bar` would pass the 421string _bar_ to the second lua script, ie., _other.lua_. 422 423read_format:<file_type>:: 424Tells Wireshark to use a specific input file type, instead of determining it 425automatically. 426 427stdin_descr:<description>:: 428Define a description for the standard input interface, instead of the default: 429"Standard input". 430-- 431 432-Y <display filter>:: 433--display-filter <display filter>:: 434Start with the given display filter. 435 436-z <statistics-string>:: 437Get Wireshark to collect various types of statistics and display the 438result in a window that updates in semi-real time. For the currently 439implemented statistics consult the Wireshark manual page. 440 441// XXX - add more details here! 442 443 444[[ChCustColorizationSection]] 445 446=== Packet colorization 447 448A very useful mechanism available in Wireshark is packet colorization. 449You can set up Wireshark so that it will colorize packets according to a 450display filter. This allows you to emphasize the packets you might be 451interested in. 452 453You can find a lot of coloring rule examples at the _Wireshark Wiki 454Coloring Rules page_ at {wireshark-wiki-url}ColoringRules. 455 456There are two types of coloring rules in Wireshark: temporary rules that 457are only in effect until you quit the program, and permanent rules that 458are saved in a preference file so that they are available the next time 459you run Wireshark. 460 461Temporary rules can be added by selecting a packet and pressing the kbd:[Ctrl] 462key together with one of the number keys. This will create a coloring rule based 463on the currently selected conversation. It will try to create a conversation 464filter based on TCP first, then UDP, then IP and at last Ethernet. Temporary 465filters can also be created by selecting the menu:Colorize with Filter[Color X] 466menu items when right-clicking in the packet detail pane. 467 468To permanently colorize packets, select menu:View[Coloring Rules...]. Wireshark 469will display the “Coloring Rules” dialog box as shown in 470<<ChCustColoringRulesDialog>>. 471 472[[ChCustColoringRulesDialog]] 473.The “Coloring Rules” dialog box 474image::wsug_graphics/ws-coloring-rules-dialog.png[{screenshot-attrs}] 475 476If this is the first time using the Coloring Rules dialog and you’re using the 477default configuration profile you should see the default rules, shown above. 478 479[NOTE] 480.The first match wins 481==== 482More specific rules should usually be listed before more general rules. For 483example, if you have a coloring rule for UDP before the one for DNS, the rule 484for DNS may not be applied (DNS is typically carried over UDP and the UDP rule 485will match first). 486==== 487 488You can create a new rule by clicking on the btn:[+] button. You can delete 489one or more rules by clicking the btn:[-] button. The “copy” button will 490duplicate a rule. 491 492You can edit a rule by double-clicking on its name or filter. In 493<<ChCustColoringRulesDialog>> the name of the rule “Checksum Errors” is being 494edited. Clicking on the btn:[Foreground] and btn:[Background] buttons will 495open a color chooser (<<ChCustChooseColorDialog>>) for the foreground (text) and 496background colors respectively. 497 498[[ChCustChooseColorDialog]] 499.A color chooser 500image::wsug_graphics/ws-choose-color-rule.png[{small-screenshot-attrs}] 501 502The color chooser appearance depends on your operating system. The macOS color 503picker is shown. Select the color you desire for the selected packets and click 504btn:[OK]. 505 506<<ChCustColorFilterMany>> shows an example of several color filters being used 507in Wireshark. Note that the frame detail shows that the “Bad TCP” rule 508was applied, along with the matching filter. 509 510[[ChCustColorFilterMany]] 511.Using color filters with Wireshark 512image::wsug_graphics/ws-coloring-fields.png[{screenshot-attrs}] 513 514 515[[ChCustProtocolDissectionSection]] 516 517=== Control Protocol dissection 518 519The user can control how protocols are dissected. 520 521Each protocol has its own dissector, so dissecting a complete packet will 522typically involve several dissectors. As Wireshark tries to find the right 523dissector for each packet (using static “routes” and heuristics “guessing”), 524it might choose the wrong dissector in your specific case. For example, 525Wireshark won’t know if you use a common protocol on an uncommon TCP port, e.g. 526using HTTP on TCP port 800 instead of the standard port 80. 527 528There are two ways to control the relations between protocol dissectors: disable 529a protocol dissector completely or temporarily divert the way Wireshark calls 530the dissectors. 531 532[[ChAdvEnabledProtocols]] 533 534==== The “Enabled Protocols” dialog box 535 536The Enabled Protocols dialog box lets you enable or disable specific protocols. 537Most protocols are enabled by default. When a protocol is disabled, Wireshark 538stops processing a packet whenever that protocol is encountered. 539 540[NOTE] 541==== 542Disabling a protocol will prevent information about higher-layer protocols from 543being displayed. For example, suppose you disabled the IP protocol and selected 544a packet containing Ethernet, IP, TCP, and HTTP information. The Ethernet 545information would be displayed, but the IP, TCP and HTTP information would not - 546disabling IP would prevent it and the higher-layer protocols from being displayed. 547==== 548 549To enable or disable protocols select menu:Analyze[Enabled Protocols...]. 550Wireshark will pop up the “Enabled Protocols” dialog box as shown in 551<<ChAdvEnabledProtocolsFig>>. 552 553[[ChAdvEnabledProtocolsFig]] 554.The “Enabled Protocols” dialog box 555image::wsug_graphics/ws-enabled-protocols.png[{screenshot-attrs}] 556 557To disable or enable a protocol, simply click the checkbox using the mouse. 558Note that typing a few letters of the protocol name in the search box will limit 559the list to those protocols that contain these letters. 560 561You can choose from the following actions: 562 563btn:[Enable All]:: Enable all protocols in the list. 564 565btn:[Disable All]:: Disable all protocols in the list. 566 567btn:[Invert]:: Toggle the state of all protocols in the list. 568 569btn:[OK]:: Save and apply the changes and close the dialog box, see <<AppFiles>> for details. 570 571btn:[Cancel]:: Cancel the changes and close the dialog box. 572 573[[ChAdvDecodeAs]] 574 575==== User Specified Decodes 576 577The “Decode As” functionality lets you temporarily divert specific protocol 578dissections. This might be useful for example, if you do some uncommon 579experiments on your network. 580 581Decode As is accessed by selecting the menu:Analyze[Decode As...]. Wireshark 582will pop up the “Decode As” dialog box as shown in <<ChAdvDecodeAsFig>>. 583 584[[ChAdvDecodeAsFig]] 585.The “Decode As” dialog box 586image::wsug_graphics/ws-decode-as.png[{screenshot-attrs}] 587 588In this dialog you are able to edit entries by means of the edit buttons on the 589left. 590 591You can also pop up this dialog box from the context menu in the packet list or 592packet details. It will then contain a new line based on the currently selected 593packet. 594 595These settings will be lost if you quit Wireshark or change profile unless you 596save the entries. 597 598btn:[+]:: Add new entry for selected packet 599 600btn:[-]:: Remove the selected entry. 601 602btn:[Copy]:: Copy the selected entry. 603 604btn:[Clear]:: Clear the list of user specified decodes. 605 606btn:[OK]:: Apply the user specified decodes and close the dialog box. 607 608btn:[Save]:: Save and apply the user specified decodes and close the dialog box. 609 610btn:[Cancel]:: Cancel the changes and close the dialog box. 611 612[[ChCustPreferencesSection]] 613 614=== Preferences 615 616There are a number of preferences you can set. Simply select the 617menu:Edit[Preferences...] (menu:Wireshark[Preferences...] on macOS) and 618Wireshark will pop up the Preferences dialog box as shown in 619<<ChCustGUIPrefPage>>, with the “User Interface” page as default. On the left 620side is a tree where you can select the page to be shown. 621 622* The btn:[OK] button will apply the preferences settings and close the dialog. 623 624// Uncomment if bug 12566 is ever fixed. 625// * The btn:[Apply] button will apply the preferences settings and keep the dialog open. 626 627* The btn:[Cancel] button will restore all preferences settings to the last saved state. 628 629[[ChCustGUIPrefPage]] 630.The preferences dialog box 631image::wsug_graphics/ws-gui-preferences.png[{screenshot-attrs}] 632 633Wireshark supports quite a few protocols, which is reflected in the long list of entries in the “Protocols” pane. 634You can jump to the preferences for a specific protocol by expanding “Protocols” and quickly typing the first few letters of the protocol name. 635 636The “Advanced” pane will let you view and edit all of Wireshark’s preferences, similar to link:about:config[] and link:chrome:flags[] in the Firefox and Chrome web browsers. 637 638.Advanced preferences 639image::wsug_graphics/ws-gui-preferences-advanced.png[{screenshot-attrs}] 640 641You can search for a preference by typing text into the “Search” entry. 642You can also pass preference names to Wireshark and TShark on the command line. 643For example, the __gui.prepend_window_title__ can be used to differentiate between different instances of Wireshark: 644 645[source,sh] 646---- 647$ wireshark -o "gui.prepend_window_title:Internal Network" & 648$ wireshark -o "gui.prepend_window_title:External Network" & 649---- 650 651[[ChCustConfigProfilesSection]] 652 653=== Configuration Profiles 654 655Configuration Profiles can be used to configure and use more than one set of 656preferences and configurations. Select the menu:Edit[Configuration Profiles...] menu item 657or press kbd:[Shift+Ctrl+A] or kbd:[Shift+{cmd}+A] (macOS) and Wireshark will pop up 658the Configuration Profiles dialog box as shown in 659<<ChCustGUIConfigProfilesPage>>. It is also possible to click in the “Profile” 660part of the statusbar to popup a menu with available Configuration Profiles 661(<<ChUseWiresharkStatusbarProfile>>). 662 663Configuration files stored in each profile include: 664 665* Preferences (preferences) (<<ChCustPreferencesSection>>) 666 667* Capture Filters (cfilters) (<<ChWorkDefineFilterSection>>) 668 669* Display Filters (dfilters) (<<ChWorkDefineFilterSection>>) 670 671* Coloring Rules (colorfilters) (<<ChCustColorizationSection>>) 672 673* Disabled Protocols (disabled_protos) (<<ChAdvEnabledProtocols>>) 674 675* User Accessible Tables: 676+ 677-- 678* Custom HTTP headers (custom_http_header_fields) 679 680* Custom IMF headers (imf_header_fields) 681 682* Custom LDAP AttributeValue types (custom_ldap_attribute_types) 683 684* Display Filter Macros (dfilter_macros) (<<ChDisplayFilterMacrosSection>>) 685 686* ESS Category Attributes (ess_category_attributes) 687 (<<ChEssCategoryAttributes>>) 688 689* MaxMind Database Paths (maxmind_db_paths) (<<ChMaxMindDbPaths>>) 690 691* K12 Protocols (k12_protos) (<<ChK12ProtocolsSection>>) 692 693* Object Identifier Names and Associated Syntaxes (<<ChObjectIdentifiers>>) 694 695* PRES Users Context List (pres_context_list) (<<ChPresContextList>>) 696 697* SCCP Users Table (sccp_users) (<<ChSccpUsers>>) 698 699* SNMP Enterprise Specific Trap Types (snmp_specific_traps) 700 (<<ChSNMPEnterpriseSpecificTrapTypes>>) 701 702* SNMP Users (snmp_users) (<<ChSNMPUsersSection>>) 703 704* User DLTs Table (user_dlts) (<<ChUserDLTsSection>>) 705 706* IKEv2 decryption table (ikev2_decryption_table) (<<ChIKEv2DecryptionSection>>) 707 708* Protobuf Search Paths (protobuf_search_paths) (<<ChProtobufSearchPaths>>) 709 710* Protobuf UDP Message Types (protobuf_udp_message_types) (<<ChProtobufUDPMessageTypes>>) 711-- 712 713* Changed dissector assignments (__decode_as_entries__), which can be set in the “Decode 714 As...” dialog box (<<ChAdvDecodeAs>>). 715 716* Some recent settings (recent), such as pane sizes in the Main window 717 (<<ChUseMainWindowSection>>), column widths in the packet list 718 (<<ChUsePacketListPaneSection>>), all selections in the menu:View[] menu 719 (<<ChUseViewMenuSection>>) and the last directory navigated to in the “File 720 Open” dialog. 721 722All other configurations are stored in the personal configuration folder and 723are common to all profiles. 724 725[[ChCustGUIConfigProfilesPage]] 726.The configuration profiles dialog box 727image::wsug_graphics/ws-gui-config-profiles.png[{medium-screenshot-attrs}] 728 729Search for profile ...:: 730The list of profiles can be filtered by entering part of the profile's name 731into the search box. 732 733Type selection:: 734Profiles can be filtered between displaying "All profiles", "Personal profiles" 735and "Global profiles" 736* Personal profiles - these are profiles stored in the user's configuration directory 737* Global profiles - these are profiles provided with Wireshark 738 739New (+):: 740Create a new profile. The name of the created profile is “New profile” 741and is highlighted so that you can more easily change it. 742 743Delete (-):: 744Deletes the selected profile. This includes all configuration files used 745in this profile. Multiple profiles can be selected and deleted at the same time. 746It is not possible to delete the “Default” profile or global profiles. 747Deletion of the "Default" profile will reset this profile. 748 749Copy:: 750Copies the selected profile. This copies the configuration of the 751profile currently selected in the list. The name of the created profile 752is the same as the copied profile, with the text “(copy)” and is 753highlighted so that you can more easily change it. 754 755btn:[Import]:: 756Profiles can be imported from zip-archives as well as directly from directory 757structures. Profiles, which already exist by name will be skipped, as well as 758profiles named "Default". 759 760btn:[Export]:: 761Profiles can be exported to a zip-archive. Global profiles, as well as the default 762profile will be skipped during export. Profiles can be selected in the list individually 763and only the selected profiles will be exported 764 765btn:[OK]:: 766This button saves all changes, applies the selected profile and closes the 767dialog. 768 769btn:[Cancel]:: 770Close this dialog. This will discard unsaved settings, new profiles will not be 771added and deleted profiles will not be deleted. 772 773btn:[Help]:: 774Show this help page. 775 776[[ChUserTable]] 777 778=== User Table 779 780The User Table editor is used for managing various tables in Wireshark. Its main 781dialog works very similarly to that of <<ChCustColorizationSection>>. 782 783[[ChDisplayFilterMacrosSection]] 784 785=== Display Filter Macros 786 787Display Filter Macros are a mechanism to create shortcuts for complex filters. 788For example defining a display filter macro named _$$tcp_conv$$_ whose text is 789 790---- 791(ip.src == $1 and ip.dst == $2 and tcp.srcport == $3 and tcp.dstport == $4) 792or (ip.src == $2 and ip.dst == $1 and tcp.srcport == $4 and tcp.dstport == $3) 793---- 794 795would allow to use a display filter like 796 797---- 798${tcp_conv:10.1.1.2;10.1.1.3;1200;1400} 799---- 800 801instead of typing the whole filter. 802 803Display Filter Macros can be managed with a user table, as described in 804<<ChUserTable>>, by selecting menu:Analyze[Display Filter Macros] from 805the menu. The User Table has the following fields: 806 807Name:: 808The name of the macro. 809 810Text:: 811The replacement text for the macro it uses $1, $2, $3, ... as the input arguments. 812 813[[ChEssCategoryAttributes]] 814 815=== ESS Category Attributes 816 817Wireshark uses this table to map ESS Security Category attributes to textual representations. The values to put in this table are usually found in a http://www.xmlspif.org/[XML SPIF], which is used for defining security labels. 818 819This table is a user table, as described in <<ChUserTable>>, with the 820following fields: 821 822Tag Set:: 823An Object Identifier representing the Category Tag Set. 824 825Value:: 826The value (Label And Cert Value) representing the Category. 827 828Name:: 829The textual representation for the value. 830 831[[ChMaxMindDbPaths]] 832 833=== MaxMind Database Paths 834 835If your copy of Wireshark supports https://www.maxmind.com/[MaxMind’s] MaxMindDB library, you can use their databases to match IP addresses to countries, cites, autonomous system numbers, and other bits of information. 836Some databases are https://dev.maxmind.com/geoip/geoip2/geolite2/[available at no cost for registered users], while others require a licensing fee. 837See https://www.maxmind.com/[the MaxMind web site] for more information. 838 839The configuration for the MaxMind database is a user table, as described 840in <<ChUserTable>>, with the following fields: 841 842Database pathname:: 843This specifies a directory containing MaxMind data files. Any files 844ending with _.mmdb_ will be automatically loaded. 845 846The locations for your data files are up to you, but `/usr/share/GeoIP` 847and `/var/lib/GeoIP` are common on Linux and `C:\ProgramData\GeoIP`, 848`C:\Program Files\Wireshark\GeoIP` might be good choices on Windows. 849 850[[ChGeoIPDbPaths]] 851 852Previous versions of Wireshark supported MaxMind's original GeoIP Legacy 853database format. They were configured similar to MaxMindDB files above, 854except GeoIP files must begin with _Geo_ and end with _.dat_. They are 855no longer supported and MaxMind stopped distributing GeoLite Legacy 856databases in April 2018. 857 858[[ChIKEv2DecryptionSection]] 859 860=== IKEv2 decryption table 861 862Wireshark can decrypt Encrypted Payloads of IKEv2 (Internet Key Exchange version 8632) packets if necessary information is provided. Note that you can decrypt only 864IKEv2 packets with this feature. If you want to decrypt IKEv1 packets or ESP 865packets, use Log Filename setting under ISAKMP protocol preference or settings 866under ESP protocol preference respectively. 867 868This is handled by a user table, as described in <<ChUserTable>>, 869with the following fields: 870 871Initiator’s SPI:: 872Initiator’s SPI of the IKE_SA. This field takes hexadecimal string without 873“0x” prefix and the length must be 16 hex chars (represents 8 octets). 874 875Responder’s SPI:: 876Responder’s SPI of the IKE_SA. This field takes hexadecimal string without 877“0x” prefix and the length must be 16 hex chars (represents 8 octets). 878 879SK_ei:: 880Key used to encrypt/decrypt IKEv2 packets from initiator to responder. This 881field takes hexadecimal string without “0x” prefix and its length must meet 882the requirement of the encryption algorithm selected. 883 884 885SK_er:: 886Key used to encrypt/decrypt IKEv2 packets from responder to initiator. This 887field takes hexadecimal string without “0x” prefix and its length must meet 888the requirement of the encryption algorithm selected. 889 890Encryption Algorithm:: 891Encryption algorithm of the IKE_SA. 892 893$$SK_ai$$:: 894Key used to calculate Integrity Checksum Data for IKEv2 packets from responder 895to initiator. This field takes hexadecimal string without “0x” prefix and its 896length must meet the requirement of the integrity algorithm selected. 897 898$$SK_ar$$:: 899Key used to calculate Integrity Checksum Data for IKEv2 packets from initiator 900to responder. This field takes hexadecimal string without “0x” prefix and its 901length must meet the requirement of the integrity algorithm selected. 902 903Integrity Algorithm:: 904Integrity algorithm of the IKE_SA. 905 906[[ChObjectIdentifiers]] 907 908=== Object Identifiers 909 910Many protocols that use ASN.1 use Object Identifiers (OIDs) to uniquely identify 911certain pieces of information. In many cases, they are used in an extension 912mechanism so that new object identifiers (and associated values) may be defined 913without needing to change the base standard. 914 915While Wireshark has knowledge about many of the OIDs and the syntax of their 916associated values, the extensibility means that other values may be encountered. 917 918Wireshark uses this table to allow the user to define the name and syntax of 919Object Identifiers that Wireshark does not know about (for example, a privately 920defined X.400 extension). It also allows the user to override the name and 921syntax of Object Identifiers that Wireshark does know about (e.g. changing the 922name “id-at-countryName” to just “c”). 923 924This table is a user table, as described in <<ChUserTable>>, with the 925following fields: 926 927OID:: 928The string representation of the Object Identifier e.g. “2.5.4.6”. 929 930Name:: 931The name that should be displayed by Wireshark when the Object Identifier is 932dissected e.g. (“c”); 933 934Syntax:: 935The syntax of the value associated with the Object Identifier. This must be one 936of the syntaxes that Wireshark already knows about (e.g. “PrintableString”). 937 938[[ChPresContextList]] 939 940=== PRES Users Context List 941 942Wireshark uses this table to map a presentation context identifier to a given 943object identifier when the capture does not contain a PRES package with a 944presentation context definition list for the conversation. 945 946This table is a user table, as described in <<ChUserTable>>, with the 947following fields: 948 949Context Id:: 950An Integer representing the presentation context identifier for which this 951association is valid. 952 953Syntax Name OID:: 954The object identifier representing the abstract syntax name, which defines the 955protocol that is carried over this association. 956 957[[ChSccpUsers]] 958 959=== SCCP users Table 960 961Wireshark uses this table to map specific protocols to a certain DPC/SSN 962combination for SCCP. 963 964This table is a user table, as described in <<ChUserTable>>, with the 965following fields: 966 967Network Indicator:: 968An Integer representing the network indicator for which this association is 969valid. 970 971Called DPCs:: 972An range of integers representing the dpcs for which this association is valid. 973 974Called SSNs:: 975An range of integers representing the ssns for which this association is valid. 976 977User protocol:: 978The protocol that is carried over this association 979 980[[ChSNMPSMIModules]] 981 982=== SMI (MIB and PIB) Modules 983 984If your copy of Wireshark supports libSMI, you can specify a list of MIB and PIB 985modules here. The COPS and SNMP dissectors can use them to resolve OIDs. 986 987Module name:: 988The name of the module, e.g. IF-MIB. 989 990[[ChSNMPSMIPaths]] 991 992=== SMI (MIB and PIB) Paths 993 994If your copy of Wireshark supports libSMI, you can specify one or more paths to 995MIB and PIB modules here. 996 997Directory name:: 998A module directory, e.g. `/usr/local/snmp/mibs`. Wireshark automatically uses 999the standard SMI path for your system, so you usually don’t have to add anything 1000here. 1001 1002[[ChSNMPEnterpriseSpecificTrapTypes]] 1003 1004=== SNMP Enterprise Specific Trap Types 1005 1006Wireshark uses this table to map specific-trap values to user defined 1007descriptions in a Trap PDU. The description is shown in the packet details 1008specific-trap element. 1009 1010This table is a user table, as described in <<ChUserTable>>, with the 1011following fields: 1012 1013Enterprise OID:: 1014The object identifier representing the object generating the trap. 1015 1016 1017Trap Id:: 1018An Integer representing the specific-trap code. 1019 1020 1021Description:: 1022The description to show in the packet details. 1023 1024[[ChSNMPUsersSection]] 1025 1026=== SNMP users Table 1027 1028Wireshark uses this table to verify authentication and to decrypt encrypted 1029SNMPv3 packets. 1030 1031This table is a user table, as described in <<ChUserTable>>, with the 1032following fields: 1033 1034Engine ID:: 1035If given this entry will be used only for packets whose engine id is this. This 1036field takes an hexadecimal string in the form 0102030405. 1037 1038Username:: 1039This is the userName. When a single user has more than one password for 1040different SNMP-engines the first entry to match both is taken, if you need a 1041catch all engine-id (empty) that entry should be the last one. 1042 1043Authentication model:: 1044Which auth model to use (either “MD5” or “SHA1”). 1045 1046Password:: 1047The authentication password. Use _\xDD_ for unprintable characters. An 1048hexadecimal password must be entered as a sequence of _\xDD_ characters. For 1049example the hex password 010203040506 must be entered as 1050_\x01\x02\x03\x04\x05\x06_. The _\_ character must be treated as an unprintable 1051character, i.e. it must be entered as _\x5C_ or _\x5c_. 1052 1053Privacy protocol:: 1054Which encryption algorithm to use (either “DES” or “AES”). 1055 1056Privacy password:: 1057The privacy password. Use _\xDD_ for unprintable characters. An hexadecimal 1058password must be entered as a sequence of _\xDD_ characters. For example the hex 1059password 010203040506 must be entered as _\x01\x02\x03\x04\x05\x06_. The _\_ 1060character must be treated as an unprintable character, i.e. it must be entered 1061as _\x5C_ or _\x5c_. 1062 1063[[ChK12ProtocolsSection]] 1064 1065=== Tektronix K12xx/15 RF5 protocols Table 1066 1067The Tektronix K12xx/15 rf5 file format uses helper files (*.stk) to identify the 1068various protocols that are used by a certain interface. Wireshark doesn’t read 1069these stk files, it uses a table that helps it identify which lowest layer 1070protocol to use. 1071 1072Stk file to protocol matching is handled by a user table, as described 1073in <<ChUserTable>>, with the following fields: 1074 1075Match string:: 1076A partial match for an stk filename, the first match wins, so if you have a 1077specific case and a general one the specific one must appear first in the list. 1078 1079Protocol:: 1080This is the name of the encapsulating protocol (the lowest layer in the packet 1081data) it can be either just the name of the protocol (e.g. mtp2, eth_withoutfcs, 1082sscf-nni ) or the name of the encapsulation protocol and the “application” 1083protocol over it separated by a colon (e.g sscop:sscf-nni, sscop:alcap, 1084sscop:nbap, ...) 1085 1086[[ChUserDLTsSection]] 1087 1088=== User DLTs protocol table 1089 1090When a pcap file uses one of the user DLTs (147 to 162) Wireshark uses this 1091table to know which protocol(s) to use for each user DLT. 1092 1093This table is a user table, as described in <<ChUserTable>>, with the 1094following fields: 1095 1096DLT:: 1097One of the user dlts. 1098 1099Payload protocol:: 1100This is the name of the payload protocol (the lowest layer in the packet data). 1101(e.g. “eth” for ethernet, “ip” for IPv4) 1102 1103Header size:: 1104If there is a header protocol (before the payload protocol) this tells which 1105size this header is. A value of 0 disables the header protocol. 1106 1107Header protocol:: 1108The name of the header protocol to be used (uses “data” as default). 1109 1110Trailer size:: 1111If there is a trailer protocol (after the payload protocol) this tells which 1112size this trailer is. A value of 0 disables the trailer protocol. 1113 1114Trailer protocol:: 1115The name of the trailer protocol to be used (uses “data” as default). 1116 1117[[ChProtobufSearchPaths]] 1118 1119=== Protobuf Search Paths 1120 1121The 1122https://developers.google.com/protocol-buffers/docs/encoding[binary wire format] 1123of Protocol Buffers (Protobuf) messages are not self-described protocol. For 1124example, the `varint` wire type in protobuf packet may be converted to int32, int64, 1125uint32, uint64, sint32, sint64, bool or enum field types of 1126https://developers.google.com/protocol-buffers/docs/proto3[protocol buffers language]. 1127Wireshark should be configured with Protocol Buffers language files (*.proto) to 1128enable proper dissection of protobuf data (which may be payload of 1129https://grpc.io/[gRPC]) based on the message, enum and field definitions. 1130 1131You can specify protobuf search paths at the Protobuf protocol preferences. 1132For example, if you defined a proto file with path `d:/my_proto_files/helloworld.proto` 1133and the `helloworld.proto` contains a line of `import "google/protobuf/any.proto";` 1134because the `any` type of official protobuf library is used. And the real path of 1135`any.proto` is `d:/protobuf-3.4.1/include/google/protobuf/any.proto`. You should 1136add the `d:/protobuf-3.4.1/include/` and `d:/my_proto_files` paths into protobuf 1137search paths. 1138 1139The configuration for the protobuf search paths is a user table, as described 1140in <<ChUserTable>>, with the following fields: 1141 1142Protobuf source directory:: 1143This specifies a directory containing protobuf source files. For example, 1144`d:/protobuf-3.4.1/include/` and `d:/my_proto_files` in Windows, or 1145`/usr/include/` and `/home/alice/my_proto_files` in Linux/UNIX. 1146 1147Load all files:: 1148If this option is enabled, Wireshark will load all *.proto files in this directory 1149and its subdirectories when Wireshark startup or protobuf search paths preferences 1150changed. Note that the source directories that configured to protobuf official or third 1151libraries path (like `d:/protobuf-3.4.1/include/`) should not be set to load all 1152files, that may cause unnecessary memory use. 1153 1154[[ChProtobufUDPMessageTypes]] 1155 1156=== Protobuf UDP Message Types 1157 1158If the payload of UDP on certain ports is Protobuf encoding, Wireshark use this table 1159to know which Protobuf message type should be used to parsing the data on the specified 1160UDP port(s). 1161 1162The configuration for UDP Port(s) to Protobuf message type maps is a user table, as 1163described in <<ChUserTable>>, with the following fields: 1164 1165UDP Ports:: 1166The range of UDP ports. The format may be "8000" or "8000,8008-8088,9080". 1167 1168Message Type:: 1169The Protobuf message type as which the data on the specified udp port(s) should be parsed. 1170The message type is allowed to be empty, that means let Protobuf to dissect the data on 1171specified UDP ports as normal wire type without precise definitions. 1172 1173Tips: You can create your own dissector to call Protobuf dissector. If your dissector is 1174written in C language, you can pass the message type to Protobuf dissector by `data` 1175parameter of call_dissector_with_data() function. If your dissector is written in Lua, you 1176can pass the message type to Protobuf dissector by `pinfo.private["pb_msg_type"]`. The format 1177of `data` and `pinfo.private["pb_msg_type"]` is 1178 1179---- 1180 "message," message_type_name 1181---- 1182 1183For example: 1184 1185---- 1186 message,helloworld.HelloRequest 1187---- 1188 1189the `helloworld` is package name, `HelloRequest` is message type. 1190 1191// End of WSUG Chapter Customizing 1192