++++++++++++++++++++++++++++++++++++++
<!-- 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.0.0 (v2.0.0rc2-85-gca5a275 from master-2.0)
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 <capture filter>      packet filter in libpcap filter syntax
  -s <snaplen>             packet snapshot length (def: 65535)
  -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)
  -D                       print list of interfaces and exit
  -L                       print list of link-layer types of 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"
  --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.

-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 `C` enables concurrent (asynchronous) DNS lookups.
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 seconts ('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.

-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
link:wireshark-wiki-site:[]ColoringRules[wireshark-wiki-site:[]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[]

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 button:[+] button. You can delete
one or more rules by clicking the button:[-] 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 button:[Foreground] and button:[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[]

The color chooser appearance depends on your operating system. The OS X color
picker is shown. Select the color you desire for the selected packets and click
button:[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[]


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

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 button:[Save] button to save your settings. The button:[OK] or
button:[Apply] buttons will not save your changes permanently and they will be
lost when Wireshark is closed.

You can choose from the following actions:

. button:[Enable All]: Enable all protocols in the list.

. button:[Disable All]: Disable all protocols in the list.

. button:[Invert]: Toggle the state of all protocols in the list.

. button:[OK]: Apply the changes and close the dialog box.

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

. button:[Save]: Save the settings to the disabled_protos, see <<AppFiles>> for details.

. button:[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[]

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

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

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

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

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

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

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

. button:[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[]

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

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

. button:[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 OS X) 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 button:[OK] button will apply the preferences settings and close the dialog.

* The button:[Apply] button will apply the preferences settings and keep the dialog open.

* The button:[Cancel] button will restore all preferences settings to the last saved state.

[[ChCustGUIPrefPage]]
.The preferences dialog box
image::wsug_graphics/ws-gui-preferences.png[]

[[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
button:[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[]

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 _Configuration Profiles..._ menu item
from the _Edit_ menu, or simply press Shift-Ctrl-A; 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 the Profiles:

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

* GeoIP Database Paths (geoip_db_paths) (<<ChGeoIPDbPaths>>)

* 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 _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 ``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[]

New::
This button adds a new profile to the profiles list. The name of the created
profile is ``New profile'' and can be changed in the Properties field.

Copy::
This button adds a new profile to the profiles list, copying all configuration
from the profile currently selected in the list. The name of the created profile
is the same as the copied profile, with the text ``(copy)'' applied. The name
can be changed in the Properties field.

Delete::
This button deletes the selected profile, including all configuration files used
in this profile. It is not possible to delete the ``Default'' profile.

Configuration Profiles::
You can select a configuration profile from this list (which will fill in the
profile name in the fields down at the bottom of the dialog box).

Profile name::
You can change the name of the currently selected profile here.
+
--
The profile name will be used as a folder name in the configured ``Personal
configurations'' folder. If adding multiple profiles with the same name, only
one profile will be created.

On Windows the profile name cannot start or end with a period (.), and cannot
contain any of the following characters: `&#x5c;', `&#x2f;', `:', `&#x2a;',
`&#x3f;', `&#x60;', `<', `>', `&#x7c;', or `&#x2b;'. On Unix the profile name
cannot contain the `&#x2f;' character.
--

button:[OK]::
This button saves all changes, applies the selected profile and closes the
dialog.

button:[Apply]::
This button saves all changes, applies the selected profile and keeps the dialog
open.

button:[Cancel]::
Close this dialog. This will discard unsaved settings, new profiles will not be
added and deleted profiles will not be deleted.

button:[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 <<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 handled by an <<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.

[[ChGeoIPDbPaths]]

=== GeoIP Database Paths

If your copy of Wireshark supports link:http://www.maxmind.com/[MaxMind's]
GeoIP library, you can use their databases to match IP addresses to countries,
cites, autonomous system numbers, ISPs, and other bits of information. Some
databases are link:http://www.maxmind.com/download/geoip/database/[available
at no cost], while others require a licensing fee. See
link:http://www.maxmind.com/app/ip-location[the MaxMind web site] for more
information.

This table is handled by an <<ChUserTable>> with the following fields.

Database pathname::
This specifies a directory containing GeoIP data files. Any files beginning with
_Geo_ and ending with _.dat_ will be automatically loaded. A total of 8 files
can be loaded.
+
The locations for your data files are up to you, but `/usr/share/GeoIP` (Linux),
`C:\GeoIP` (Windows), `C:\Program Files\Wireshark\GeoIP` (Windows) might be good
choices.

[[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 table is handled by an <<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 handled by an <<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 handled by an <<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 handled by an <<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 handled by an <<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 handled by an <<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 an <<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 handled by an <<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 -->
++++++++++++++++++++++++++++++++++++++
