aboutsummaryrefslogtreecommitdiffstats
path: root/docbook/wsug_src/WSUG_chapter_customize.asciidoc
blob: ae920cdf71cfa0c76d1f11b16ba42bded71cea9b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
++++++++++++++++++++++++++++++++++++++
<!-- 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 <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 -->
++++++++++++++++++++++++++++++++++++++