// WSUG Chapter Customizing

[#ChapterCustomize]

== Customizing Wireshark

[#ChCustIntroduction]

=== Introduction

Wireshark’s default behavior 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
launch 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::images/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::images/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::images/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::images/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::images/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::images/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 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::images/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::images/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 an 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::
A range of integers representing the dpcs for which this association is valid.

Called SSNs::
A 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 a 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. A
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. A 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 dissector table

When a pcap file uses one of the user DLTs (147 to 162) Wireshark uses this
table to know which dissector(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 dissector::
This is the name of the payload dissector (the lowest layer in the packet data).
(e.g., “eth_withfcs, "eth_withoutfcs”, and "eth_maybefcs" respectively for Ethernet frames that do, do not, or might possibly include the FCS at the end, “ip” for trying IPv4 then IPv6)

Header size::
If there is a header (before the payload) this tells which
size this header is. A value of 0 disables the header dissector.

Header dissector::
The name of the header dissector to be used (uses “data” as default).

Trailer size::
If there is a trailer (after the payload) this tells which
size this trailer is. A value of 0 disables the trailer dissector.

Trailer dissector::
The name of the trailer dissector 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