diff options
Diffstat (limited to 'docbook/wsug_src/WSUG_chapter_customize.adoc')
-rw-r--r-- | docbook/wsug_src/WSUG_chapter_customize.adoc | 1191 |
1 files changed, 0 insertions, 1191 deletions
diff --git a/docbook/wsug_src/WSUG_chapter_customize.adoc b/docbook/wsug_src/WSUG_chapter_customize.adoc deleted file mode 100644 index bba03b1b15..0000000000 --- a/docbook/wsug_src/WSUG_chapter_customize.adoc +++ /dev/null @@ -1,1191 +0,0 @@ -// WSUG Chapter Customizing - -[[ChapterCustomize]] - -== Customizing Wireshark - -[[ChCustIntroduction]] - -=== Introduction - -Wireshark’s default behaviour will usually suit your needs pretty well. However, -as you become more familiar with Wireshark, it can be customized in various ways -to suit your needs even better. In this chapter we explore: - -* How to start Wireshark with command line parameters - -* How to colorize the packet list - -* How to control protocol dissection - -* How to use the various preference settings - -[[ChCustCommandLine]] - -=== Start Wireshark from the command line - -You can start Wireshark from the command line, but it can also be started from -most Window managers as well. In this section we will look at starting it from -the command line. - -Wireshark supports a large number of command line parameters. To see what they -are, simply enter the command _wireshark -h_ and the help information shown in -<<ChCustEx1>> (or something similar) should be printed. - -[[ChCustEx1]] -.Help information available from Wireshark ----- -include::wireshark-h.txt[] ----- - -We will examine each of the command line options in turn. - -The first thing to notice is that issuing the command `wireshark` by itself will -bring up Wireshark. However, you can include as many of the command line -parameters as you like. Their meanings are as follows ( in alphabetical order ): - -// XXX - is the alphabetical order a good choice? Maybe better task based? - --a <capture autostop condition>:: ---autostop <capture autostop condition>:: -Specify a criterion that specifies when Wireshark is to stop writing -to a capture file. The criterion is of the form test:value, where test -is one of: -+ --- - duration:value:: - Stop writing to a capture file after value of seconds have elapsed. - - filesize:value:: - Stop writing to a capture file after it reaches a size of value - kilobytes (where a kilobyte is 1000 bytes, not 1024 bytes). If - this option is used together with the -b option, Wireshark will - stop writing to the current capture file and switch to the next - one if filesize is reached. - - files:value:: - Stop writing to capture files after value number of files were - written. - - packets:value:: - Stop writing to a capture file after value number of packets were written. --- - --b <capture ring buffer option>:: -If a maximum capture file size was specified, this option causes Wireshark to -run in “ring buffer” mode, with the specified number of files. In “ring -buffer” mode, Wireshark will write to several capture files. Their -name is based on the number of the file and on the creation date and -time. -+ -When the first capture file fills up Wireshark will switch to writing -to the next file, and so on. With the files option it’s -also possible to form a “ring buffer.” This will fill up new files until the -number of files specified, at which point the data in the first file will be -discarded so a new file can be written. -+ -If the optional duration is specified, Wireshark will also -switch to the next file when the specified number of seconds has elapsed even -if the current file is not completely filled up. -+ --- - duration:value:: - Switch to the next file after value seconds have elapsed, even - if the current file is not completely filled up. - - filesize:value:: - Switch to the next file after it reaches a size of value kilobytes - (where a kilobyte is 1000 bytes, not 1024 bytes). - - files:value:: - Begin again with the first file after value number of files were - written (form a ring buffer). - - packets:value:: - Switch to the next file after value number of packets were written, even - if the current file is not completely filled up. - - interval:value:: - Switch to the next file when the time is an exact multiple of value seconds. --- - --B <capture buffer size>:: ---buffer-size <capture buffer size>:: -Set capture buffer size (in MB, default is 2MB). This is used by the capture -driver to buffer packet data until that data can be written to disk. If you -encounter packet drops while capturing, try to increase this size. Not supported -on some platforms. - --C <config profile>:: -Start with the specified configuration profile. - --c <capture packet count>:: -This option specifies the maximum number of packets to capture when capturing -live data. It would be used in conjunction with the `-k` option. - ---capture-comment <comment>:: -Add the comment string to the capture file, if supported by the file format. - --d <layer_type>==<selector>,<decode_as_protocol>:: -"Decode As", see <<ChAdvDecodeAs>> for details. Example: tcp.port==8888,http - --D:: ---list-interfaces:: -Print a list of the interfaces on which Wireshark can capture, then exit. For -each network interface, a number and an interface name, possibly followed by a -text description of the interface, is printed. The interface name or the number -can be supplied to the `-i` flag to specify an interface on which to capture. -+ -This can be useful on systems that don’t have a command to list them (e.g., -Windows systems, or UNIX systems lacking `ifconfig -a`). The number can be -especially useful on Windows, where the interface name is a GUID. -+ -Note that “can capture” means that Wireshark was able to open that device to -do a live capture. If, on your system, a program doing a network capture must be -run from an account with special privileges, then, if -Wireshark is run with the `-D` flag and is not run from such an account, it will -not list any interfaces. - ---display <DISPLAY>:: -Set the X display to use, instead of the one defined in the environment, or -the default display. - ---enable-protocol <proto_name>:: ---disable-protocol <proto_name>:: -Enable and disable the dissection of the protocol. - ---enable-heuristic <short_name>:: ---disable-heuristic <short_name>:: -Enable and disable the dissection of the heuristic protocol. - --f <capture filter>:: -This option sets the initial capture filter expression to be used when capturing -packets. - ---fullscreen:: -Start Wireshark in full screen. - --g <packet number>:: -After reading in a capture file using the -r flag, go to the given packet -number. - --h:: ---help:: -This option requests Wireshark to print its version and usage instructions -(as shown here) and exit. - --H:: -Hide the capture info dialog during live packet capture. - --i <capture interface>:: ---interface <capture interface>:: -Set the name of the network interface or pipe to use for live packet capture. -+ -Network interface names should match one of the names listed in `wireshark -D` -(described above). A number, as reported by `wireshark -D`, can also be used. If -you’re using UNIX, `netstat -i`, `ifconfig -a` or `ip link` might also work to -list interface names, although not all versions of UNIX support the `-a` flag to -`ifconfig`. -+ -If no interface is specified, Wireshark searches the list of interfaces, -choosing the first non-loopback interface if there are any non-loopback -interfaces, and choosing the first loopback interface if there are no -non-loopback interfaces; if there are no interfaces, Wireshark reports an error -and doesn’t start the capture. -+ -Pipe names should be either the name of a FIFO (named pipe) or “-” to read -data from the standard input. Data read from pipes must be in standard libpcap -format. - --J <jump filter>:: -After reading in a capture file using the `-r` flag, jump to the first packet -which matches the filter expression. The filter expression is in display filter -format. If an exact match cannot be found the first packet afterwards is -selected. - --I:: ---monitor-mode:: -Capture wireless packets in monitor mode if available. - --j:: -Use this option after the `-J` option to search backwards for a first packet to -go to. - --k:: -The `-k` option specifies that Wireshark should start capturing packets -immediately. This option requires the use of the `-i` parameter to specify the -interface that packet capture will occur from. - --K <keytab file>:: -Use the specified file for Kerberos decryption. - --l:: -This option turns on automatic scrolling if the packet list pane is being -updated automatically as packets arrive during a capture (as specified by the -`-S` flag). - --L:: ---list-data-link-types:: -List the data link types supported by the interface and exit. - ---list-time-stamp-types:: -List timestamp types configurable for the interface and exit. - --m <font>:: -This option sets the name of the font used for most text displayed by Wireshark. - -// XXX - add an example! - --n:: -Disable network object name resolution (such as hostname, TCP and UDP port -names). - --N <name resolving flags>:: -Turns on name resolving for particular types of addresses and port numbers. The -argument is a string that may contain the following letters: -+ --- - N:: - Use external name resolver. - - d:: - Enable name resolution from captured DNS packets. - - m:: - Enable MAC address resolution. - - n:: - Enable network address resolution. - - t:: - Enable transport layer port number resolution. - - v:: - Enable VLAN ID resolution. --- - --o <preference or recent settings>:: -Sets a preference or recent value, overriding the default value and any value -read from a preference or recent file. The argument to the flag is a string of -the form _prefname:value_, where _prefname_ is the name of the preference (which -is the same name that would appear in the `preferences` or `recent` file), and -_value_ is the value to which it should be set. Multiple instances of `-o -<preference settings> ` can be given on a single command line. -+ --- -An example of setting a single preference would be: - ----- -wireshark -o mgcp.display_dissect_tree:TRUE ----- - -An example of setting multiple preferences would be: ----- -wireshark -o mgcp.display_dissect_tree:TRUE -o mgcp.udp.callagent_port:2627 ----- - -You can get a list of all available preference strings from the -preferences file. See <<AppFiles>> for details. - -User access tables can be overridden using “uat,” followed by -the UAT file name and a valid record for the file: - ----- -wireshark -o "uat:user_dlts:\"User 0 (DLT=147)\",\"http\",\"0\",\"\",\"0\",\"\"" ----- - -The example above would dissect packets with a libpcap data link type 147 as -HTTP, just as if you had configured it in the DLT_USER protocol preferences. --- - --p:: ---no-promiscuous-mode:: -Don’t put the interface into promiscuous mode. Note that the interface might be -in promiscuous mode for some other reason. Hence, `-p` cannot be used to ensure -that the only traffic that is captured is traffic sent to or from the machine on -which Wireshark is running, broadcast traffic, and multicast traffic to -addresses received by that machine. - --P <path setting>:: -Special path settings usually detected automatically. This is used for special -cases, e.g. starting Wireshark from a known location on an USB stick. -+ -The criterion is of the form key:path, where key is one of: -+ --- - persconf:path:: - Path of personal configuration files, like the preferences files. - - persdata:path:: - Path of personal data files, it’s the folder initially opened. After the - initialization, the recent file will keep the folder last used. --- - --r <infile>:: ---read-file <infile>:: -This option provides the name of a capture file for Wireshark to read and -display. This capture file can be in one of the formats Wireshark understands. - --R <read (display) filter>:: ---read-filter <read (display) filter>:: -This option specifies a display filter to be applied when reading packets from a -capture file. The syntax of this filter is that of the display filters discussed -in <<ChWorkDisplayFilterSection>>. Packets not matching the filter -are discarded. - --s <capture snapshot length>:: ---snapshot-length <capture snapshot length>:: -This option specifies the snapshot length to use when capturing packets. -Wireshark will only capture _snaplen_ bytes of data for each packet. - --S:: -This option specifies that Wireshark will display packets as it captures them. -This is done by capturing in one process and displaying them in a separate -process. This is the same as “Update list of packets in real time” in the -“Capture Options” dialog box. - --t <time stamp format>:: -This option sets the format of packet timestamps that are displayed in the -packet list window. The format can be one of: -+ --- -r:: Relative, which specifies timestamps are -displayed relative to the first packet captured. - -a:: Absolute, which specifies that actual times -be displayed for all packets. - -ad:: Absolute with date, which specifies that -actual dates and times be displayed for all packets. - -adoy:: Absolute with YYYY/DOY date, which specifies that -actual dates and times be displayed for all packets. - -d:: Delta, which specifies that timestamps -are relative to the previous packet. - -dd: Delta, which specifies that timestamps -are relative to the previous displayed packet. - -e:: Epoch, which specifies that timestamps -are seconds since epoch (Jan 1, 1970 00:00:00) - -u:: Absolute, which specifies that actual times -be displayed for all packets in UTC. - -ud:: Absolute with date, which specifies that -actual dates and times be displayed for all packets in UTC. - -udoy:: Absolute with YYYY/DOY date, which specifies that -actual dates and times be displayed for all packets in UTC. --- - --u <s | hms>:: -Show timesamps as seconds (“s”, the default) or hours, minutes, and seconds (“hms”) - --v:: ---version:: -This option requests Wireshark to print out its version information and -exit. - --w <savefile>:: -This option sets the name of the file to be used to save captured packets. -This can be '-' for stdout. - --y <capture link type>:: ---link-type <capture like types>:: -If a capture is started from the command line with `-k`, set the data -link type to use while capturing packets. The values reported by `-L` -are the values that can be used. - ---time-stamp-type <type>:: -If a capture is started from the command line with `-k`, set the time -stamp type to use while capturing packets. The values reported by -`--list-time-stamp-types` are the values that can be used. - --X <eXtension option>:: -Specify an option to be passed to a Wireshark/Tshark module. The eXtension -option is in the form extension_key:value, where extension_key can be: -+ --- -lua_script:<lua_script_filename>:: -Tells Wireshark to load the given script in addition to the default Lua scripts. - -lua_script[num]:argument:: -Tells Wireshark to pass the given argument to the lua script identified by -_num_, which is the number indexed order of the _lua_script_ command. For -example, if only one script was loaded with `-X lua_script:my.lua`, then `-X -lua_script1:foo` will pass the string _foo_ to the _my.lua_ script. If two -scripts were loaded, such as `-X lua_script:my.lua -X lua_script:other.lua` -in that order, then a `-X lua_script2:bar` would pass the -string _bar_ to the second lua script, ie., _other.lua_. - -read_format:<file_type>:: -Tells Wireshark to use a specific input file type, instead of determining it -automatically. - -stdin_descr:<description>:: -Define a description for the standard input interface, instead of the default: -"Standard input". --- - --Y <display filter>:: ---display-filter <display filter>:: -Start with the given display filter. - --z <statistics-string>:: -Get Wireshark to collect various types of statistics and display the -result in a window that updates in semi-real time. For the currently -implemented statistics consult the Wireshark manual page. - -// XXX - add more details here! - - -[[ChCustColorizationSection]] - -=== Packet colorization - -A very useful mechanism available in Wireshark is packet colorization. -You can set up Wireshark so that it will colorize packets according to a -display filter. This allows you to emphasize the packets you might be -interested in. - -You can find a lot of coloring rule examples at the _Wireshark Wiki -Coloring Rules page_ at {wireshark-wiki-url}ColoringRules. - -There are two types of coloring rules in Wireshark: temporary rules that -are only in effect until you quit the program, and permanent rules that -are saved in a preference file so that they are available the next time -you run Wireshark. - -Temporary rules can be added by selecting a packet and pressing the kbd:[Ctrl] -key together with one of the number keys. This will create a coloring rule based -on the currently selected conversation. It will try to create a conversation -filter based on TCP first, then UDP, then IP and at last Ethernet. Temporary -filters can also be created by selecting the menu:Colorize with Filter[Color X] -menu items when right-clicking in the packet detail pane. - -To permanently colorize packets, select menu:View[Coloring Rules...]. Wireshark -will display the “Coloring Rules” dialog box as shown in -<<ChCustColoringRulesDialog>>. - -[[ChCustColoringRulesDialog]] -.The “Coloring Rules” dialog box -image::wsug_graphics/ws-coloring-rules-dialog.png[{screenshot-attrs}] - -If this is the first time using the Coloring Rules dialog and you’re using the -default configuration profile you should see the default rules, shown above. - -[NOTE] -.The first match wins -==== -More specific rules should usually be listed before more general rules. For -example, if you have a coloring rule for UDP before the one for DNS, the rule -for DNS may not be applied (DNS is typically carried over UDP and the UDP rule -will match first). -==== - -You can create a new rule by clicking on the btn:[+] button. You can delete -one or more rules by clicking the btn:[-] button. The “copy” button will -duplicate a rule. - -You can edit a rule by double-clicking on its name or filter. In -<<ChCustColoringRulesDialog>> the name of the rule “Checksum Errors” is being -edited. Clicking on the btn:[Foreground] and btn:[Background] buttons will -open a color chooser (<<ChCustChooseColorDialog>>) for the foreground (text) and -background colors respectively. - -[[ChCustChooseColorDialog]] -.A color chooser -image::wsug_graphics/ws-choose-color-rule.png[{small-screenshot-attrs}] - -The color chooser appearance depends on your operating system. The macOS color -picker is shown. Select the color you desire for the selected packets and click -btn:[OK]. - -<<ChCustColorFilterMany>> shows an example of several color filters being used -in Wireshark. Note that the frame detail shows that the “Bad TCP” rule -was applied, along with the matching filter. - -[[ChCustColorFilterMany]] -.Using color filters with Wireshark -image::wsug_graphics/ws-coloring-fields.png[{screenshot-attrs}] - - -[[ChCustProtocolDissectionSection]] - -=== Control Protocol dissection - -The user can control how protocols are dissected. - -Each protocol has its own dissector, so dissecting a complete packet will -typically involve several dissectors. As Wireshark tries to find the right -dissector for each packet (using static “routes” and heuristics “guessing”), -it might choose the wrong dissector in your specific case. For example, -Wireshark won’t know if you use a common protocol on an uncommon TCP port, e.g. -using HTTP on TCP port 800 instead of the standard port 80. - -There are two ways to control the relations between protocol dissectors: disable -a protocol dissector completely or temporarily divert the way Wireshark calls -the dissectors. - -[[ChAdvEnabledProtocols]] - -==== The “Enabled Protocols” dialog box - -The Enabled Protocols dialog box lets you enable or disable specific protocols. -Most protocols are enabled by default. When a protocol is disabled, Wireshark -stops processing a packet whenever that protocol is encountered. - -[NOTE] -==== -Disabling a protocol will prevent information about higher-layer protocols from -being displayed. For example, suppose you disabled the IP protocol and selected -a packet containing Ethernet, IP, TCP, and HTTP information. The Ethernet -information would be displayed, but the IP, TCP and HTTP information would not - -disabling IP would prevent it and the higher-layer protocols from being displayed. -==== - -To enable or disable protocols select menu:Analyze[Enabled Protocols...]. -Wireshark will pop up the “Enabled Protocols” dialog box as shown in -<<ChAdvEnabledProtocolsFig>>. - -[[ChAdvEnabledProtocolsFig]] -.The “Enabled Protocols” dialog box -image::wsug_graphics/ws-enabled-protocols.png[{screenshot-attrs}] - -To disable or enable a protocol, simply click the checkbox using the mouse. -Note that typing a few letters of the protocol name in the search box will limit -the list to those protocols that contain these letters. - -You can choose from the following actions: - -btn:[Enable All]:: Enable all protocols in the list. - -btn:[Disable All]:: Disable all protocols in the list. - -btn:[Invert]:: Toggle the state of all protocols in the list. - -btn:[OK]:: Save and apply the changes and close the dialog box, see <<AppFiles>> for details. - -btn:[Cancel]:: Cancel the changes and close the dialog box. - -[[ChAdvDecodeAs]] - -==== User Specified Decodes - -The “Decode As” functionality lets you temporarily divert specific protocol -dissections. This might be useful for example, if you do some uncommon -experiments on your network. - -Decode As is accessed by selecting the menu:Analyze[Decode As...]. Wireshark -will pop up the “Decode As” dialog box as shown in <<ChAdvDecodeAsFig>>. - -[[ChAdvDecodeAsFig]] -.The “Decode As” dialog box -image::wsug_graphics/ws-decode-as.png[{screenshot-attrs}] - -In this dialog you are able to edit entries by means of the edit buttons on the -left. - -You can also pop up this dialog box from the context menu in the packet list or -packet details. It will then contain a new line based on the currently selected -packet. - -These settings will be lost if you quit Wireshark or change profile unless you -save the entries. - -btn:[+]:: Add new entry for selected packet - -btn:[-]:: Remove the selected entry. - -btn:[Copy]:: Copy the selected entry. - -btn:[Clear]:: Clear the list of user specified decodes. - -btn:[OK]:: Apply the user specified decodes and close the dialog box. - -btn:[Save]:: Save and apply the user specified decodes and close the dialog box. - -btn:[Cancel]:: Cancel the changes and close the dialog box. - -[[ChCustPreferencesSection]] - -=== Preferences - -There are a number of preferences you can set. Simply select the -menu:Edit[Preferences...] (menu:Wireshark[Preferences...] on macOS) and -Wireshark will pop up the Preferences dialog box as shown in -<<ChCustGUIPrefPage>>, with the “User Interface” page as default. On the left -side is a tree where you can select the page to be shown. - -* The btn:[OK] button will apply the preferences settings and close the dialog. - -// Uncomment if bug 12566 is ever fixed. -// * The btn:[Apply] button will apply the preferences settings and keep the dialog open. - -* The btn:[Cancel] button will restore all preferences settings to the last saved state. - -[[ChCustGUIPrefPage]] -.The preferences dialog box -image::wsug_graphics/ws-gui-preferences.png[{screenshot-attrs}] - -Wireshark supports quite a few protocols, which is reflected in the long list of entries in the “Protocols” pane. -You can jump to the preferences for a specific protocol by expanding “Protocols” and quickly typing the first few letters of the protocol name. - -The “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. - -.Advanced preferences -image::wsug_graphics/ws-gui-preferences-advanced.png[{screenshot-attrs}] - -You can search for a preference by typing text into the “Search” entry. -You can also pass preference names to Wireshark and TShark on the command line. -For example, the __gui.prepend_window_title__ can be used to differentiate between different instances of Wireshark: - -[source,sh] ----- -$ wireshark -o "gui.prepend_window_title:Internal Network" & -$ wireshark -o "gui.prepend_window_title:External Network" & ----- - -[[ChCustConfigProfilesSection]] - -=== Configuration Profiles - -Configuration Profiles can be used to configure and use more than one set of -preferences and configurations. Select the menu:Edit[Configuration Profiles...] menu item -or press kbd:[Shift+Ctrl+A] or kbd:[Shift+{cmd}+A] (macOS) and Wireshark will pop up -the Configuration Profiles dialog box as shown in -<<ChCustGUIConfigProfilesPage>>. It is also possible to click in the “Profile” -part of the statusbar to popup a menu with available Configuration Profiles -(<<ChUseWiresharkStatusbarProfile>>). - -Configuration files stored in each profile include: - -* Preferences (preferences) (<<ChCustPreferencesSection>>) - -* Capture Filters (cfilters) (<<ChWorkDefineFilterSection>>) - -* Display Filters (dfilters) (<<ChWorkDefineFilterSection>>) - -* Coloring Rules (colorfilters) (<<ChCustColorizationSection>>) - -* Disabled Protocols (disabled_protos) (<<ChAdvEnabledProtocols>>) - -* User Accessible Tables: -+ --- -* Custom HTTP headers (custom_http_header_fields) - -* Custom IMF headers (imf_header_fields) - -* Custom LDAP AttributeValue types (custom_ldap_attribute_types) - -* Display Filter Macros (dfilter_macros) (<<ChDisplayFilterMacrosSection>>) - -* ESS Category Attributes (ess_category_attributes) - (<<ChEssCategoryAttributes>>) - -* MaxMind Database Paths (maxmind_db_paths) (<<ChMaxMindDbPaths>>) - -* K12 Protocols (k12_protos) (<<ChK12ProtocolsSection>>) - -* Object Identifier Names and Associated Syntaxes (<<ChObjectIdentifiers>>) - -* PRES Users Context List (pres_context_list) (<<ChPresContextList>>) - -* SCCP Users Table (sccp_users) (<<ChSccpUsers>>) - -* SNMP Enterprise Specific Trap Types (snmp_specific_traps) - (<<ChSNMPEnterpriseSpecificTrapTypes>>) - -* SNMP Users (snmp_users) (<<ChSNMPUsersSection>>) - -* User DLTs Table (user_dlts) (<<ChUserDLTsSection>>) - -* IKEv2 decryption table (ikev2_decryption_table) (<<ChIKEv2DecryptionSection>>) - -* Protobuf Search Paths (protobuf_search_paths) (<<ChProtobufSearchPaths>>) - -* Protobuf UDP Message Types (protobuf_udp_message_types) (<<ChProtobufUDPMessageTypes>>) --- - -* Changed dissector assignments (__decode_as_entries__), which can be set in the “Decode - As...” dialog box (<<ChAdvDecodeAs>>). - -* Some recent settings (recent), such as pane sizes in the Main window - (<<ChUseMainWindowSection>>), column widths in the packet list - (<<ChUsePacketListPaneSection>>), all selections in the menu:View[] menu - (<<ChUseViewMenuSection>>) and the last directory navigated to in the “File - Open” dialog. - -All other configurations are stored in the personal configuration folder and -are common to all profiles. - -[[ChCustGUIConfigProfilesPage]] -.The configuration profiles dialog box -image::wsug_graphics/ws-gui-config-profiles.png[{medium-screenshot-attrs}] - -Search for profile ...:: -The list of profiles can be filtered by entering part of the profile's name -into the search box. - -Type selection:: -Profiles can be filtered between displaying "All profiles", "Personal profiles" -and "Global profiles" -* Personal profiles - these are profiles stored in the user's configuration directory -* Global profiles - these are profiles provided with Wireshark - -New (+):: -Create a new profile. The name of the created profile is “New profile” -and is highlighted so that you can more easily change it. - -Delete (-):: -Deletes the selected profile. This includes all configuration files used -in this profile. Multiple profiles can be selected and deleted at the same time. -It is not possible to delete the “Default” profile or global profiles. -Deletion of the "Default" profile will reset this profile. - -Copy:: -Copies the selected profile. This copies the configuration of the -profile currently selected in the list. The name of the created profile -is the same as the copied profile, with the text “(copy)” and is -highlighted so that you can more easily change it. - -btn:[Import]:: -Profiles can be imported from zip-archives as well as directly from directory -structures. Profiles, which already exist by name will be skipped, as well as -profiles named "Default". - -btn:[Export]:: -Profiles can be exported to a zip-archive. Global profiles, as well as the default -profile will be skipped during export. Profiles can be selected in the list individually -and only the selected profiles will be exported - -btn:[OK]:: -This button saves all changes, applies the selected profile and closes the -dialog. - -btn:[Cancel]:: -Close this dialog. This will discard unsaved settings, new profiles will not be -added and deleted profiles will not be deleted. - -btn:[Help]:: -Show this help page. - -[[ChUserTable]] - -=== User Table - -The User Table editor is used for managing various tables in Wireshark. Its main -dialog works very similarly to that of <<ChCustColorizationSection>>. - -[[ChDisplayFilterMacrosSection]] - -=== Display Filter Macros - -Display Filter Macros are a mechanism to create shortcuts for complex filters. -For example defining a display filter macro named _$$tcp_conv$$_ whose text is - ----- -(ip.src == $1 and ip.dst == $2 and tcp.srcport == $3 and tcp.dstport == $4) -or (ip.src == $2 and ip.dst == $1 and tcp.srcport == $4 and tcp.dstport == $3) ----- - -would allow to use a display filter like - ----- -${tcp_conv:10.1.1.2;10.1.1.3;1200;1400} ----- - -instead of typing the whole filter. - -Display Filter Macros can be managed with a user table, as described in -<<ChUserTable>>, by selecting menu:Analyze[Display Filter Macros] from -the menu. The User Table has the following fields: - -Name:: -The name of the macro. - -Text:: -The replacement text for the macro it uses $1, $2, $3, ... as the input arguments. - -[[ChEssCategoryAttributes]] - -=== ESS Category Attributes - -Wireshark 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. - -This table is a user table, as described in <<ChUserTable>>, with the -following fields: - -Tag Set:: -An Object Identifier representing the Category Tag Set. - -Value:: -The value (Label And Cert Value) representing the Category. - -Name:: -The textual representation for the value. - -[[ChMaxMindDbPaths]] - -=== MaxMind Database Paths - -If 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. -Some databases are https://dev.maxmind.com/geoip/geoip2/geolite2/[available at no cost for registered users], while others require a licensing fee. -See https://www.maxmind.com/[the MaxMind web site] for more information. - -The configuration for the MaxMind database is a user table, as described -in <<ChUserTable>>, with the following fields: - -Database pathname:: -This specifies a directory containing MaxMind data files. Any files -ending with _.mmdb_ will be automatically loaded. - -The locations for your data files are up to you, but `/usr/share/GeoIP` -and `/var/lib/GeoIP` are common on Linux and `C:\ProgramData\GeoIP`, -`C:\Program Files\Wireshark\GeoIP` might be good choices on Windows. - -[[ChGeoIPDbPaths]] - -Previous versions of Wireshark supported MaxMind's original GeoIP Legacy -database format. They were configured similar to MaxMindDB files above, -except GeoIP files must begin with _Geo_ and end with _.dat_. They are -no longer supported and MaxMind stopped distributing GeoLite Legacy -databases in April 2018. - -[[ChIKEv2DecryptionSection]] - -=== IKEv2 decryption table - -Wireshark can decrypt Encrypted Payloads of IKEv2 (Internet Key Exchange version -2) packets if necessary information is provided. Note that you can decrypt only -IKEv2 packets with this feature. If you want to decrypt IKEv1 packets or ESP -packets, use Log Filename setting under ISAKMP protocol preference or settings -under ESP protocol preference respectively. - -This is handled by a user table, as described in <<ChUserTable>>, -with the following fields: - -Initiator’s SPI:: -Initiator’s SPI of the IKE_SA. This field takes hexadecimal string without -“0x” prefix and the length must be 16 hex chars (represents 8 octets). - -Responder’s SPI:: -Responder’s SPI of the IKE_SA. This field takes hexadecimal string without -“0x” prefix and the length must be 16 hex chars (represents 8 octets). - -SK_ei:: -Key used to encrypt/decrypt IKEv2 packets from initiator to responder. This -field takes hexadecimal string without “0x” prefix and its length must meet -the requirement of the encryption algorithm selected. - - -SK_er:: -Key used to encrypt/decrypt IKEv2 packets from responder to initiator. This -field takes hexadecimal string without “0x” prefix and its length must meet -the requirement of the encryption algorithm selected. - -Encryption Algorithm:: -Encryption algorithm of the IKE_SA. - -$$SK_ai$$:: -Key used to calculate Integrity Checksum Data for IKEv2 packets from responder -to initiator. This field takes hexadecimal string without “0x” prefix and its -length must meet the requirement of the integrity algorithm selected. - -$$SK_ar$$:: -Key used to calculate Integrity Checksum Data for IKEv2 packets from initiator -to responder. This field takes hexadecimal string without “0x” prefix and its -length must meet the requirement of the integrity algorithm selected. - -Integrity Algorithm:: -Integrity algorithm of the IKE_SA. - -[[ChObjectIdentifiers]] - -=== Object Identifiers - -Many protocols that use ASN.1 use Object Identifiers (OIDs) to uniquely identify -certain pieces of information. In many cases, they are used in an extension -mechanism so that new object identifiers (and associated values) may be defined -without needing to change the base standard. - -While Wireshark has knowledge about many of the OIDs and the syntax of their -associated values, the extensibility means that other values may be encountered. - -Wireshark uses this table to allow the user to define the name and syntax of -Object Identifiers that Wireshark does not know about (for example, a privately -defined X.400 extension). It also allows the user to override the name and -syntax of Object Identifiers that Wireshark does know about (e.g. changing the -name “id-at-countryName” to just “c”). - -This table is a user table, as described in <<ChUserTable>>, with the -following fields: - -OID:: -The string representation of the Object Identifier e.g. “2.5.4.6”. - -Name:: -The name that should be displayed by Wireshark when the Object Identifier is -dissected e.g. (“c”); - -Syntax:: -The syntax of the value associated with the Object Identifier. This must be one -of the syntaxes that Wireshark already knows about (e.g. “PrintableString”). - -[[ChPresContextList]] - -=== PRES Users Context List - -Wireshark uses this table to map a presentation context identifier to a given -object identifier when the capture does not contain a PRES package with a -presentation context definition list for the conversation. - -This table is a user table, as described in <<ChUserTable>>, with the -following fields: - -Context Id:: -An Integer representing the presentation context identifier for which this -association is valid. - -Syntax Name OID:: -The object identifier representing the abstract syntax name, which defines the -protocol that is carried over this association. - -[[ChSccpUsers]] - -=== SCCP users Table - -Wireshark uses this table to map specific protocols to a certain DPC/SSN -combination for SCCP. - -This table is a user table, as described in <<ChUserTable>>, with the -following fields: - -Network Indicator:: -An Integer representing the network indicator for which this association is -valid. - -Called DPCs:: -An range of integers representing the dpcs for which this association is valid. - -Called SSNs:: -An range of integers representing the ssns for which this association is valid. - -User protocol:: -The protocol that is carried over this association - -[[ChSNMPSMIModules]] - -=== SMI (MIB and PIB) Modules - -If your copy of Wireshark supports libSMI, you can specify a list of MIB and PIB -modules here. The COPS and SNMP dissectors can use them to resolve OIDs. - -Module name:: -The name of the module, e.g. IF-MIB. - -[[ChSNMPSMIPaths]] - -=== SMI (MIB and PIB) Paths - -If your copy of Wireshark supports libSMI, you can specify one or more paths to -MIB and PIB modules here. - -Directory name:: -A module directory, e.g. `/usr/local/snmp/mibs`. Wireshark automatically uses -the standard SMI path for your system, so you usually don’t have to add anything -here. - -[[ChSNMPEnterpriseSpecificTrapTypes]] - -=== SNMP Enterprise Specific Trap Types - -Wireshark uses this table to map specific-trap values to user defined -descriptions in a Trap PDU. The description is shown in the packet details -specific-trap element. - -This table is a user table, as described in <<ChUserTable>>, with the -following fields: - -Enterprise OID:: -The object identifier representing the object generating the trap. - - -Trap Id:: -An Integer representing the specific-trap code. - - -Description:: -The description to show in the packet details. - -[[ChSNMPUsersSection]] - -=== SNMP users Table - -Wireshark uses this table to verify authentication and to decrypt encrypted -SNMPv3 packets. - -This table is a user table, as described in <<ChUserTable>>, with the -following fields: - -Engine ID:: -If given this entry will be used only for packets whose engine id is this. This -field takes an hexadecimal string in the form 0102030405. - -Username:: -This is the userName. When a single user has more than one password for -different SNMP-engines the first entry to match both is taken, if you need a -catch all engine-id (empty) that entry should be the last one. - -Authentication model:: -Which auth model to use (either “MD5” or “SHA1”). - -Password:: -The authentication password. Use _\xDD_ for unprintable characters. An -hexadecimal password must be entered as a sequence of _\xDD_ characters. For -example the hex password 010203040506 must be entered as -_\x01\x02\x03\x04\x05\x06_. The _\_ character must be treated as an unprintable -character, i.e. it must be entered as _\x5C_ or _\x5c_. - -Privacy protocol:: -Which encryption algorithm to use (either “DES” or “AES”). - -Privacy password:: -The privacy password. Use _\xDD_ for unprintable characters. An hexadecimal -password must be entered as a sequence of _\xDD_ characters. For example the hex -password 010203040506 must be entered as _\x01\x02\x03\x04\x05\x06_. The _\_ -character must be treated as an unprintable character, i.e. it must be entered -as _\x5C_ or _\x5c_. - -[[ChK12ProtocolsSection]] - -=== Tektronix K12xx/15 RF5 protocols Table - -The Tektronix K12xx/15 rf5 file format uses helper files (*.stk) to identify the -various protocols that are used by a certain interface. Wireshark doesn’t read -these stk files, it uses a table that helps it identify which lowest layer -protocol to use. - -Stk file to protocol matching is handled by a user table, as described -in <<ChUserTable>>, with the following fields: - -Match string:: -A partial match for an stk filename, the first match wins, so if you have a -specific case and a general one the specific one must appear first in the list. - -Protocol:: -This is the name of the encapsulating protocol (the lowest layer in the packet -data) it can be either just the name of the protocol (e.g. mtp2, eth_withoutfcs, -sscf-nni ) or the name of the encapsulation protocol and the “application” -protocol over it separated by a colon (e.g sscop:sscf-nni, sscop:alcap, -sscop:nbap, ...) - -[[ChUserDLTsSection]] - -=== User DLTs protocol table - -When a pcap file uses one of the user DLTs (147 to 162) Wireshark uses this -table to know which protocol(s) to use for each user DLT. - -This table is a user table, as described in <<ChUserTable>>, with the -following fields: - -DLT:: -One of the user dlts. - -Payload protocol:: -This is the name of the payload protocol (the lowest layer in the packet data). -(e.g. “eth” for ethernet, “ip” for IPv4) - -Header size:: -If there is a header protocol (before the payload protocol) this tells which -size this header is. A value of 0 disables the header protocol. - -Header protocol:: -The name of the header protocol to be used (uses “data” as default). - -Trailer size:: -If there is a trailer protocol (after the payload protocol) this tells which -size this trailer is. A value of 0 disables the trailer protocol. - -Trailer protocol:: -The name of the trailer protocol to be used (uses “data” as default). - -[[ChProtobufSearchPaths]] - -=== Protobuf Search Paths - -The -https://developers.google.com/protocol-buffers/docs/encoding[binary wire format] -of Protocol Buffers (Protobuf) messages are not self-described protocol. For -example, the `varint` wire type in protobuf packet may be converted to int32, int64, -uint32, uint64, sint32, sint64, bool or enum field types of -https://developers.google.com/protocol-buffers/docs/proto3[protocol buffers language]. -Wireshark should be configured with Protocol Buffers language files (*.proto) to -enable proper dissection of protobuf data (which may be payload of -https://grpc.io/[gRPC]) based on the message, enum and field definitions. - -You can specify protobuf search paths at the Protobuf protocol preferences. -For example, if you defined a proto file with path `d:/my_proto_files/helloworld.proto` -and the `helloworld.proto` contains a line of `import "google/protobuf/any.proto";` -because the `any` type of official protobuf library is used. And the real path of -`any.proto` is `d:/protobuf-3.4.1/include/google/protobuf/any.proto`. You should -add the `d:/protobuf-3.4.1/include/` and `d:/my_proto_files` paths into protobuf -search paths. - -The configuration for the protobuf search paths is a user table, as described -in <<ChUserTable>>, with the following fields: - -Protobuf source directory:: -This specifies a directory containing protobuf source files. For example, -`d:/protobuf-3.4.1/include/` and `d:/my_proto_files` in Windows, or -`/usr/include/` and `/home/alice/my_proto_files` in Linux/UNIX. - -Load all files:: -If this option is enabled, Wireshark will load all *.proto files in this directory -and its subdirectories when Wireshark startup or protobuf search paths preferences -changed. Note that the source directories that configured to protobuf official or third -libraries path (like `d:/protobuf-3.4.1/include/`) should not be set to load all -files, that may cause unnecessary memory use. - -[[ChProtobufUDPMessageTypes]] - -=== Protobuf UDP Message Types - -If the payload of UDP on certain ports is Protobuf encoding, Wireshark use this table -to know which Protobuf message type should be used to parsing the data on the specified -UDP port(s). - -The configuration for UDP Port(s) to Protobuf message type maps is a user table, as -described in <<ChUserTable>>, with the following fields: - -UDP Ports:: -The range of UDP ports. The format may be "8000" or "8000,8008-8088,9080". - -Message Type:: -The Protobuf message type as which the data on the specified udp port(s) should be parsed. -The message type is allowed to be empty, that means let Protobuf to dissect the data on -specified UDP ports as normal wire type without precise definitions. - -Tips: You can create your own dissector to call Protobuf dissector. If your dissector is -written in C language, you can pass the message type to Protobuf dissector by `data` -parameter of call_dissector_with_data() function. If your dissector is written in Lua, you -can pass the message type to Protobuf dissector by `pinfo.private["pb_msg_type"]`. The format -of `data` and `pinfo.private["pb_msg_type"]` is - ----- - "message," message_type_name ----- - -For example: - ----- - message,helloworld.HelloRequest ----- - -the `helloworld` is package name, `HelloRequest` is message type. - -// End of WSUG Chapter Customizing |