path: root/docbook/wsug_src/WSUG_chapter_customize.asciidoc

// 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
====
----
Wireshark 2.1.0 (v2.1.0rc0-502-g328fbc0 from master)
Interactively dump and analyze network traffic.
See https://www.wireshark.org for more information.

Usage: wireshark [options] ... [ <infile> ]

Capture interface:
  -i <interface>           name or idx of interface (def: first non-loopback)
  -f <capfilter|predef:>   packet filter in libpcap filter syntax or
                           predef:filtername - predefined filtername from GUI
  -s <snaplen>             packet snapshot length (def: 262144)
  -p                       don’t capture in promiscuous mode
  -k                       start capturing immediately (def: do nothing)
  -S                       update packet display when new packets are captured
  -l                       turn on automatic scrolling while -S is in use
  -I                       capture in monitor mode, if available
  -B <buffer size>         size of kernel buffer (def: 2MB)
  -y <link type>           link layer type (def: first appropriate)
  --time-stamp-type <type> timestamp method for interface
  -D                       print list of interfaces and exit
  -L                       print list of link-layer types of iface and exit
  --list-time-stamp-types  print list of timestamp types for iface and exit

Capture stop conditions:
  -c <packet count>        stop after n packets (def: infinite)
  -a <autostop cond.> ...  duration:NUM - stop after NUM seconds
                           filesize:NUM - stop this file after NUM KB
                              files:NUM - stop after NUM files
Capture output:
  -b <ringbuffer opt.> ... duration:NUM - switch to next file after NUM secs
                           filesize:NUM - switch to next file after NUM KB
                              files:NUM - ringbuffer: replace after NUM files
RPCAP options:
  -A <user>:<password>     use RPCAP password authentication
Input file:
  -r <infile>              set the filename to read from (no pipes or stdin!)

Processing:
  -R <read filter>         packet filter in Wireshark display filter syntax
  -n                       disable all name resolutions (def: all enabled)
  -N <name resolve flags>  enable specific name resolution(s): "mnNtCd"
  -d <layer_type>==<selector>,<decode_as_protocol> ...
                           "Decode As”, see the man page for details
                           Example: tcp.port==8888,http
  --disable-protocol <proto_name>
                           disable dissection of proto_name
  --enable-heuristic <short_name>
                           enable dissection of heuristic protocol
  --disable-heuristic <short_name>
                           disable dissection of heuristic protocol

User interface:
  -C <config profile>      start with specified configuration profile
  -Y <display filter>      start with the given display filter
  -g <packet number>       go to specified packet number after "-r"
  -J <jump filter>         jump to the first packet matching the (display)
                           filter
  -j                       search backwards for a matching packet after "-J"
  -m <font>                set the font name used for most text
  -t a|ad|d|dd|e|r|u|ud    output format of time stamps (def: r: rel. to first)
  -u s|hms                 output format of seconds (def: s: seconds)
  -X <key>:<value>         eXtension options, see man page for details
  -z <statistics>          show various statistics, see man page for details

Output:
  -w <outfile|->           set the output filename (or '-' for stdout)

Miscellaneous:
  -h                       display this help and exit
  -v                       display version info and exit
  -P <key>:<path>          persconf:path - personal configuration files
                           persdata:path - personal data files
  -o <name>:<value> ...    override preference or recent setting
  -K <keytab>              keytab file to use for kerberos decryption
----
====

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>::
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.
--

-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 <command>files</command> 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 <command>duration</command> 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 fills up.
+
--
    duration</command>:value::
    Switch to the next file after value seconds have elapsed, even
    if the current file is not completely filled up.

    filesize</command>:value::
    Switch to the next file after it reaches a size of value kilobytes
    (where a kilobyte is 1000 bytes, not 1024 bytes).

    files</command>:value::
    Begin again with the first file after value number of files were
    written (form a ring buffer).
--

-B <capture buffer size>::

Set capture buffer size (in MB, default is 1MB). 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 <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.

-D::

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 (for example, as root), then, if
Wireshark is run with the `-D` flag and is not run from such an account, it will
not list any interfaces.

-f <capture filter>::

This option sets the initial capture filter expression to be used when capturing
packets.

-g <packet number>::

After reading in a capture file using the -r flag, go to the given packet
number.

-h::

The `-h` option requests Wireshark to print its version and usage instructions
(as shown above) and exit.

-i <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` or `ifconfig -a` 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::

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 the data link types supported by the interface and exit.

--list-time-stamp-types::

List timestamp types configurable for the iface 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 letters `m` to enable MAC address
resolution, `n` to enable network address resolution, and `t` to enable
transport-layer port number resolution. This overrides `-n` if both `-N` and
`-n` are present. The letter `d` enables resolution from captured DNS packets.

-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::

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.
--

-Q::

This option forces Wireshark to exit when capturing is complete. It can be used
with the `-c` option. It must be used in conjunction with the `-i` and `-w`
options.

-r <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>::

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>::

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.

d:: Delta, which specifies that timestamps
are relative to the previous packet.

e:: Epoch, which specifies that timestamps
are seconds since epoch (Jan 1, 1970 00:00:00)
--

-u <s | hms>::

Show timesamps as seconds (“s”, the default) or hours, minutes, and seconds (“hms”)

-v::

The `-v` 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.

-y <capture link type>::

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 data
link 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 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` and `-X
lua_script:other.lua` in that order, then a `-X lua_script2:bar` would pass the
string _bar_ to the second lua script, namely _other.lua_.
--

-z <statistics-string>::
Get Wireshark to collect various types of statistics and display the
result in a window that updates in semi-real time.

// 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 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.
All 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 other 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 on it using the mouse or press the
space bar when the protocol is highlighted. Note that typing the first few
letters of the protocol name when the Enabled Protocols dialog box is active
will temporarily open a search text box and automatically select the first
matching protocol name (if it exists).

You must use the btn:[Save] button to save your settings. The btn:[OK] or
btn:[Apply] buttons will not save your changes permanently and they will be
lost when Wireshark is closed.

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]: Apply the changes and close the dialog box.

. btn:[Apply]: Apply the changes and keep the dialog box open.

. btn:[Save]: Save the settings to the disabled_protos, 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}]

The content of this dialog box depends on the selected packet when it was opened.

These settings will be lost if you quit Wireshark or change profile unless you
save the entries in the _Show User Specified Decodes..._ windows
(<<ChAdvDecodeAsShow>>).

. btn:[Decode]: Decode packets the selected way.

. btn:[Do not decode]: Do not decode packets the selected way.

. btn:[Link/Network/Transport]: Specify the network layer at which “Decode
  As” should take place. Which of these pages are available depends on the
  content of the selected packet when this dialog box is opened.

. btn:[Show Current]: Open a dialog box showing the current list of user
  specified decodes.

. btn:[OK]: Apply the currently selected decode and close the dialog box.

. btn:[Apply]: Apply the currently selected decode and keep the dialog box
  open.

. btn:[Cancel]: Cancel the changes and close the dialog box.

[[ChAdvDecodeAsShow]]

==== Show User Specified Decodes

This dialog box shows the currently active user specified decodes. These entries
can be saved into current profile for later session.

[[ChAdvDecodeAsShowFig]]
.The “Decode As: Show” dialog box
image::wsug_graphics/ws-decode-as-show.png[{screenshot-attrs}]

. btn:[OK]: Close this dialog box.

. btn:[Save]: Save the entries in the table into current profile.

. btn:[Clear]: Removes all user specified decodes without updating the profile.

[[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.

* 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}]

[[ChCustInterfaceOptionsSection]]

==== Interface Options

In the “Capture” preferences it is possible to configure several options for the
interfaces available on your computer. Select the “Capture” pane and press the
btn:[Edit] button. In this window it is possible to change the default
link-layer header type for the interface, add a comment or choose to hide a
interface from other parts of the program.

[[ChCustInterfaceOptionsPage]]
.The interface options dialog box
image::wsug_graphics/ws-gui-interface-options.png[{screenshot-attrs}]

Each row contains options for each interface available on your computer.

* Device: the device name provided by the operating system.

* Description: provided by the operating system.

* Default link-layer: each interface may provide several link-layer header
  types. The default link-layer chosen here is the one used when you first start
  Wireshark. It is also possible to change this value in <<ChCapCaptureOptions>>
  when you start a capture. For a detailed description, see
  <<ChCapLinkLayerHeader>>.

* Comment: a user provided description of the interface. This comment will be
  used as a description instead of the operating system description.

* Hide?: enable this option to hide the interface from other parts of the program.

[[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>>)
--

* Changed dissector assignments (__decode_as_entries__), which can be set in the “Decode
  As...” dialog box (<<ChAdvDecodeAs>>), and further saved in the “User
  Specified Decodes...” window (<<ChAdvDecodeAsShow>>).

* 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}]

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. It is not possible to delete the “Default” profile or global
profiles.

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:[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 link:$$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
link:http://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
link:https://dev.maxmind.com/geoip/geoip2/downloadable/[available at no
cost], while others require a licensing fee. See
link:http://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.

Whilst 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_witoutfcs,
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).

// End of WSUG Chapter Customizing