| blob | 9076ac8ec46b7342d911fcdd98b27bd0241f689d |
1 <!-- WSUG Chapter Customizing -->
2 <!-- $Id$ -->
4 <chapter id="ChapterCustomize">
5 <title>Customizing Wireshark</title>
7 <section id="ChCustIntroduction"><title>Introduction</title>
8 <para>
9 Wireshark's default behaviour will usually suit your needs pretty well.
10 However, as you become more familiar with Wireshark, it can be customized
11 in various ways to suit your needs even better. In this chapter we explore:
12 <itemizedlist>
13 <listitem>
14 <para>
15 How to start Wireshark with command line parameters
16 </para>
17 </listitem>
18 <listitem>
19 <para>
20 How to colorize the packet list
21 </para>
22 </listitem>
23 <listitem>
24 <para>
25 How to control protocol dissection
26 </para>
27 </listitem>
28 <listitem>
29 <para>
30 How to use the various preference settings
31 </para>
32 </listitem>
33 </itemizedlist>
34 </para>
35 </section>
37 <section id="ChCustCommandLine"><title>Start Wireshark from the command line</title>
38 <para>
39 You can start <application>Wireshark</application> from the command
40 line, but it can also be started from most Window managers
41 as well. In this section we will look at starting it from the command
42 line.
43 </para>
44 <para>
45 <application>Wireshark</application> supports a large number of
46 command line parameters. To see what they are, simply enter the
47 command <command>wireshark -h</command> and the help information
48 shown in <xref linkend="ChCustEx1"/> (or something similar) should be
49 printed.
50 <example id="ChCustEx1">
51 <title>Help information available from Wireshark</title>
52 <programlisting>
53 Wireshark 1.9.0 (SVN Rev 47047 from /trunk)
54 Interactively dump and analyze network traffic.
55 See http://www.wireshark.org for more information.
57 Copyright 1998-2013 Gerald Combs <gerald@wireshark.org> and contributors.
58 This is free software; see the source for copying conditions. There is NO
59 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
61 Usage: wireshark [options] ... [ <infile> ]
63 Capture interface:
64 -i <interface> name or idx of interface (def: first non-loopback)
65 -f <capture filter> packet filter in libpcap filter syntax
66 -s <snaplen> packet snapshot length (def: 65535)
67 -p don't capture in promiscuous mode
68 -k start capturing immediately (def: do nothing)
69 -S update packet display when new packets are captured
70 -l turn on automatic scrolling while -S is in use
71 -I capture in monitor mode, if available
72 -B <buffer size> size of kernel buffer (def: 1MB)
73 -y <link type> link layer type (def: first appropriate)
74 -D print list of interfaces and exit
75 -L print list of link-layer types of iface and exit
77 Capture stop conditions:
78 -c <packet count> stop after n packets (def: infinite)
79 -a <autostop cond.> ... duration:NUM - stop after NUM seconds
80 filesize:NUM - stop this file after NUM KB
81 files:NUM - stop after NUM files
82 Capture output:
83 -b <ringbuffer opt.> ... duration:NUM - switch to next file after NUM secs
84 filesize:NUM - switch to next file after NUM KB
85 files:NUM - ringbuffer: replace after NUM files
86 Input file:
87 -r <infile> set the filename to read from (no pipes or stdin!)
89 Processing:
90 -R <read filter> packet filter in Wireshark display filter syntax
91 -n disable all name resolutions (def: all enabled)
92 -N <name resolve flags> enable specific name resolution(s): "mntC"
94 User interface:
95 -C <config profile> start with specified configuration profile
96 -d <display filter> start with the given display filter
97 -g <packet number> go to specified packet number after "-r"
98 -J <jump filter> jump to the first packet matching the (display)
99 filter
100 -j search backwards for a matching packet after "-J"
101 -m <font> set the font name used for most text
102 -t ad|a|r|d|dd|e output format of time stamps (def: r: rel. to first)
103 -u s|hms output format of seconds (def: s: seconds)
104 -X <key>:<value> eXtension options, see man page for details
105 -z <statistics> show various statistics, see man page for details
107 Output:
108 -w <outfile|-> set the output filename (or '-' for stdout)
110 Miscellaneous:
111 -h display this help and exit
112 -v display version info and exit
113 -P <key>:<path> persconf:path - personal configuration files
114 persdata:path - personal data files
115 -o <name>:<value> ... override preference or recent setting
116 -K <keytab> keytab file to use for kerberos decryption
117 --display=DISPLAY X display to use
119 </programlisting>
120 </example>
122 We will examine each of the command line options in turn.
123 </para>
124 <para>
125 The first thing to notice is that issuing the command
126 <command>wireshark</command> by itself will bring up
127 <application>Wireshark</application>.
128 However, you can include as many of the command line parameters as
129 you like. Their meanings are as follows ( in alphabetical order ):
130 XXX - is the alphabetical order a good choice? Maybe better task based?
131 <variablelist>
132 <varlistentry><term><command>-a <capture autostop condition></command></term>
133 <listitem>
134 <para>
135 Specify a criterion that specifies when Wireshark is to stop writing
136 to a capture file. The criterion is of the form test:value, where test
137 is one of:
138 <variablelist>
139 <varlistentry><term><command>duration</command>:value</term>
140 <listitem><para>
141 Stop writing to a capture file after value of seconds have elapsed.
142 </para></listitem>
143 </varlistentry>
144 <varlistentry><term><command>filesize</command>:value</term>
145 <listitem><para>
146 Stop writing to a capture file after it reaches a size of value
147 kilobytes (where a kilobyte is 1000 bytes, not 1024 bytes). If
148 this option is used together with the -b option, Wireshark will
149 stop writing to the current capture file and switch to the next
150 one if filesize is reached.
151 </para></listitem>
152 </varlistentry>
153 <varlistentry><term><command>files</command>:value</term>
154 <listitem><para>
155 Stop writing to capture files after value number of files were
156 written.
157 </para></listitem>
158 </varlistentry>
159 </variablelist>
160 </para>
161 </listitem>
162 </varlistentry>
163 <varlistentry><term><command>-b <capture ring buffer option></command></term>
164 <listitem>
165 <para>
166 If a maximum capture file size was specified, this option causes Wireshark to run
167 in "ring buffer" mode, with the specified number of files. In "ring
168 buffer" mode, Wireshark will write to several capture files. Their
169 name is based on the number of the file and on the creation date and
170 time.
171 </para>
172 <para>
173 When the first capture file fills up Wireshark will switch to writing
174 to the next file, and so on. With the <command>files</command> option it's
175 also possible to form a "ring buffer." This will fill up new files until the
176 number of files specified, at which point the data in the first file will be
177 discarded so a new file can be written.
178 </para>
179 <para>
180 If the optional <command>duration</command> is specified, Wireshark will also
181 switch to the next file when the specified number of seconds has elapsed even
182 if the current file is not completely fills up.
183 </para>
184 <para>
185 <variablelist>
186 <varlistentry><term><command>duration</command>:value</term>
187 <listitem><para>
188 Switch to the next file after value seconds have elapsed, even
189 if the current file is not completely filled up.
190 </para></listitem>
191 </varlistentry>
192 <varlistentry><term><command>filesize</command>:value</term>
193 <listitem><para>
194 Switch to the next file after it reaches a size of value kilobytes
195 (where a kilobyte is 1000 bytes, not 1024 bytes).
196 </para></listitem>
197 </varlistentry>
198 <varlistentry><term><command>files</command>:value</term>
199 <listitem><para>
200 Begin again with the first file after value number of files were
201 written (form a ring buffer).
202 </para></listitem>
203 </varlistentry>
204 </variablelist>
205 </para>
206 </listitem>
207 </varlistentry>
208 <varlistentry><term><command>-B <capture buffer size (Win32 only)></command></term>
209 <listitem>
210 <para>
211 Win32 only: set capture buffer size (in MB, default is 1MB). This
212 is used by the capture driver to buffer packet data until that
213 data can be written to disk. If you encounter packet drops while
214 capturing, try to increase this size.
215 </para>
216 </listitem>
217 </varlistentry>
218 <varlistentry><term><command>-c <capture packet count></command></term>
219 <listitem>
220 <para>
221 This option specifies the maximum number of packets to capture
222 when capturing live data. It would be used in conjunction
223 with the <command>-k</command> option.
224 </para>
225 </listitem>
226 </varlistentry>
227 <varlistentry><term><command>-D</command></term>
228 <listitem>
229 <para>
230 Print a list of the interfaces on which Wireshark can capture, and
231 exit. For each network interface, a number and an
232 interface name, possibly followed by a text description of the
233 interface, is printed. The interface name or the number can be supplied
234 to the <command>-i</command> flag to specify an interface on which to capture.
235 </para>
236 <para>
237 This can be useful on systems that don't have a command to list them
238 (e.g., Windows systems, or UNIX systems lacking <command>ifconfig -a</command>);
239 the number can be useful on Windows 2000 and later systems, where the
240 interface name is a somewhat complex string.
241 </para>
242 <para>
243 Note that "can capture" means that Wireshark was able to open
244 that device to do a live capture; if, on your system, a program doing a
245 network capture must be run from an account with special privileges (for
246 example, as root), then, if Wireshark is run with the <command>-D</command> flag and
247 is not run from such an account, it will not list any interfaces.
248 </para>
249 </listitem>
250 </varlistentry>
251 <varlistentry><term><command>-f <capture filter></command></term>
252 <listitem>
253 <para>
254 This option sets the initial capture filter expression to
255 be used when capturing packets.
256 </para>
257 </listitem>
258 </varlistentry>
259 <varlistentry><term><command>-g <packet number></command></term>
260 <listitem>
261 <para>
262 After reading in a capture file using the -r flag, go to the given
263 packet number.
264 </para>
265 </listitem>
266 </varlistentry>
267 <varlistentry><term><command>-h</command></term>
268 <listitem>
269 <para>
270 The <command>-h</command> option requests Wireshark to print
271 its version and usage instructions (as shown above) and exit.
272 </para>
273 </listitem>
274 </varlistentry>
275 <varlistentry><term><command>-i <capture interface></command></term>
276 <listitem>
277 <para>
278 Set the name of the network interface or pipe to use for live packet
279 capture.
280 </para>
281 <para>
282 Network interface names should match one of the names listed in
283 <command>wireshark -D</command> (described above); a number, as reported by
284 <command>wireshark -D</command>, can also be used. If you're using UNIX, <command>netstat
285 -i</command> or <command>ifconfig -a</command> might also work to list interface names,
286 although not all versions of UNIX support the <command>-a</command> flag to <command>ifconfig</command>.
287 </para>
288 <para>
289 If no interface is specified, Wireshark searches the list of
290 interfaces, choosing the first non-loopback interface if there are any
291 non-loopback interfaces, and choosing the first loopback interface if
292 there are no non-loopback interfaces; if there are no interfaces,
293 Wireshark reports an error and doesn't start the capture.
294 </para>
295 <para>
296 Pipe names should be either the name of a FIFO (named pipe) or ``-'' to
297 read data from the standard input. Data read from pipes must be in
298 standard libpcap format.
299 </para>
300 </listitem>
301 </varlistentry>
302 <varlistentry><term><command>-J <jump filter></command></term>
303 <listitem>
304 <para>
305 After reading in a capture file using the <command>-r</command>
306 flag, jump to the first packet which matches the filter expression.
307 The filter expression is in display filter format. If an exact match
308 cannot be found the first packet afterwards is selected.
309 </para>
310 </listitem>
311 </varlistentry>
312 <varlistentry><term><command>-j</command></term>
313 <listitem>
314 <para>
315 Use this option after the <command>-J</command> option to search
316 backwards for a first packet to go to.
317 </para>
318 </listitem>
319 </varlistentry>
320 <varlistentry><term><command>-k</command></term>
321 <listitem>
322 <para>
323 The <command>-k</command> option specifies that Wireshark
324 should start capturing packets immediately. This option
325 requires the use of the <command>-i</command> parameter to
326 specify the interface that packet capture will occur from.
327 </para>
328 </listitem>
329 </varlistentry>
330 <varlistentry><term><command>-l</command></term>
331 <listitem>
332 <para>
333 This option turns on automatic scrolling if the packet
334 list pane is being updated automatically as packets arrive
335 during a capture ( as specified by the <command>-S</command>
336 flag).
337 </para>
338 </listitem>
339 </varlistentry>
340 <varlistentry><term><command>-L</command></term>
341 <listitem>
342 <para>
343 List the data link types supported by the interface and exit.
344 </para>
345 </listitem>
346 </varlistentry>
347 <varlistentry><term><command>-m <font></command></term>
348 <listitem>
349 <para>
350 This option sets the name of the font used for most text
351 displayed by Wireshark. XXX - add an example!
352 </para>
353 </listitem>
354 </varlistentry>
355 <varlistentry><term><command>-n</command></term>
356 <listitem>
357 <para>
358 Disable network object name resolution (such as hostname, TCP and UDP
359 port names).
360 </para>
361 </listitem>
362 </varlistentry>
363 <varlistentry><term><command>-N <name resolving flags></command></term>
364 <listitem>
365 <para>
366 Turns on name resolving for particular types of addresses
367 and port numbers; the argument is a string that may contain
368 the letters <command>m</command> to enable MAC address
369 resolution, <command>n</command> to enable network address
370 resolution, and <command>t</command> to enable transport-layer
371 port number resolution. This overrides <command>-n</command>
372 if both <command>-N</command> and <command>-n</command> are
373 present. The letter C enables concurrent (asynchronous) DNS lookups.
374 </para>
375 </listitem>
376 </varlistentry>
377 <varlistentry>
378 <term><command>-o <preference/recent settings></command></term>
379 <listitem>
380 <para>
381 Sets a preference or recent value, overriding the default value and
382 any value read from a preference/recent file. The argument to the
383 flag is a string of the form prefname:value, where prefname
384 is the name of the preference (which is the same name that
385 would appear in the preference/recent file), and value is the value
386 to which it should be set. Multiple instances of
387 <command>-o <preference settings> </command> can be
388 given on a single command line.
389 </para>
390 <para>An example of setting a single preference would be: </para>
391 <para>
392 <command>
393 wireshark -o mgcp.display_dissect_tree:TRUE
394 </command>
395 </para>
396 <para>
397 An example of setting multiple preferences would be:
398 </para>
399 <para>
400 <command>
401 wireshark -o mgcp.display_dissect_tree:TRUE -o mgcp.udp.callagent_port:2627
402 </command>
403 </para>
404 <tip><title>Tip!</title>
405 <para>
406 You can get a list of all available preference strings from the
407 preferences file, see <xref linkend="AppFiles"/>.
408 </para>
409 </tip>
410 <para>User access tables can be overridden using "uat," followed by
411 the UAT file name and a valid record for the file: </para>
412 <para>
413 <command>
414 wireshark -o "uat:user_dlts:\"User 0 (DLT=147)\",\"http\",\"0\",\"\",\"0\",\"\""
415 </command>
416 </para>
417 <para>
418 The example above would dissect packets with a libpcap data
419 link type 147 as HTTP, just as if you had configured it in the
420 DLT_USER protocol preferences.
421 </para>
422 </listitem>
423 </varlistentry>
424 <varlistentry><term><command>-p</command></term>
425 <listitem>
426 <para>
427 Don't put the interface into promiscuous mode. Note that
428 the interface might be in promiscuous mode for some other
429 reason; hence, -p cannot be used to ensure that the only
430 traffic that is captured is traffic sent to or from the
431 machine on which Wireshark is running, broadcast traffic, and
432 multicast traffic to addresses received by that machine.
433 </para>
434 </listitem>
435 </varlistentry>
436 <varlistentry><term><command>-P <path setting></command></term>
437 <listitem>
438 <para>
439 Special path settings usually detected automatically. This is used
440 for special cases, e.g. starting Wireshark from a known location on
441 an USB stick.
442 </para>
443 <para>
444 The criterion is of the form key:path, where key is one of:
445 <variablelist>
446 <varlistentry><term><command>persconf</command>:path</term>
447 <listitem><para>
448 path of personal configuration files, like the preferences files.
449 </para></listitem>
450 </varlistentry>
451 <varlistentry><term><command>persdata</command>:path</term>
452 <listitem><para>
453 path of personal data files, it's the folder initially opened.
454 After the initialization, the recent file will keep the folder
455 last used.
456 </para></listitem>
457 </varlistentry>
458 </variablelist>
459 </para>
460 </listitem>
461 </varlistentry>
462 <varlistentry><term><command>-Q</command></term>
463 <listitem>
464 <para>
465 This option forces Wireshark to exit when capturing is
466 complete. It can be used with the <command>-c</command> option.
467 It must be used in conjunction with the
468 <command>-i</command> and <command>-w</command> options.
469 </para>
470 </listitem>
471 </varlistentry>
472 <varlistentry><term><command>-r <infile></command></term>
473 <listitem>
474 <para>
475 This option provides the name of a capture file for Wireshark
476 to read and display. This capture file can be in one of the
477 formats Wireshark understands.
478 </para>
479 </listitem>
480 </varlistentry>
481 <varlistentry><term><command>-R <read (display) filter></command></term>
482 <listitem>
483 <para>
484 This option specifies a display filter to be applied when
485 reading packets from a capture file. The syntax of this
486 filter is that of the display filters discussed in
487 <xref linkend="ChWorkDisplayFilterSection"/>. Packets not
488 matching the filter are discarded.
489 </para>
490 </listitem>
491 </varlistentry>
492 <varlistentry><term><command>-s <capture snaplen></command></term>
493 <listitem>
494 <para>
495 This option specifies the snapshot length to use when
496 capturing packets. Wireshark will only capture
497 <command><snaplen></command> bytes of data for each packet.
498 </para>
499 </listitem>
500 </varlistentry>
501 <varlistentry><term><command>-S</command></term>
502 <listitem>
503 <para>
504 This option specifies that Wireshark will display packets as
505 it captures them. This is done by capturing in one process
506 and displaying them in a separate process. This is the same
507 as "Update list of packets in real time" in the Capture Options
508 dialog box.
509 </para>
510 </listitem>
511 </varlistentry>
512 <varlistentry>
513 <term><command>-t <time stamp format></command></term>
514 <listitem>
515 <para>
516 This option sets the format of packet timestamps that are
517 displayed in the packet list window. The format can be one of:
518 <itemizedlist>
519 <listitem>
520 <para>
521 <command>r</command> relative, which specifies timestamps are
522 displayed relative to the first packet captured.
523 </para>
524 </listitem>
525 <listitem>
526 <para>
527 <command>a</command> absolute, which specifies that actual times
528 be displayed for all packets.
529 </para>
530 </listitem>
531 <listitem>
532 <para>
533 <command>ad</command> absolute with date, which specifies that
534 actual dates and times be displayed for all packets.
535 </para>
536 </listitem>
537 <listitem>
538 <para>
539 <command>d</command> delta, which specifies that timestamps
540 are relative to the previous packet.
541 </para>
542 </listitem>
543 <listitem>
544 <para>
545 <command>e</command> epoch, which specifies that timestamps
546 are seconds since epoch (Jan 1, 1970 00:00:00)
547 </para>
548 </listitem>
549 </itemizedlist>
550 </para>
551 </listitem>
552 </varlistentry>
553 <varlistentry><term><command>-v</command></term>
554 <listitem>
555 <para>
556 The <command>-v</command> option requests
557 Wireshark to print out its version information and exit.
558 </para>
559 </listitem>
560 </varlistentry>
561 <varlistentry><term><command>-w <savefile></command></term>
562 <listitem>
563 <para>
564 This option sets the name of the <command>savefile</command>
565 to be used when saving a capture file.
566 </para>
567 </listitem>
568 </varlistentry>
569 <varlistentry><term><command>-y <capture link type></command></term>
570 <listitem>
571 <para>
572 If a capture is started from the command line with -k, set the data
573 link type to use while capturing packets. The values reported by -L
574 are the values that can be used.
575 </para>
576 </listitem>
577 </varlistentry>
578 <varlistentry><term><command>-X <eXtension option></command></term>
579 <listitem>
580 <para>
581 Specify an option to be passed to a TShark module. The eXtension
582 option is in the form extension_key:value, where extension_key can
583 be:
584 </para>
585 <para>
586 <command>lua_script</command>:lua_script_filename; Tells Wireshark to load the given script in addition to the default Lua scripts.
587 </para>
588 </listitem>
589 </varlistentry>
590 <varlistentry><term><command>-z <statistics-string></command></term>
591 <listitem>
592 <para>
593 Get Wireshark to collect various types of statistics and display the
594 result in a window that updates in semi-real time.
595 XXX - add more details here!
596 </para>
597 </listitem>
598 </varlistentry>
599 </variablelist>
600 </para>
601 </section>
603 <section id="ChCustColorizationSection"><title>Packet colorization</title>
604 <para>
605 A very useful mechanism available in Wireshark is packet colorization.
606 You can set-up Wireshark so that it will colorize packets according to a
607 filter. This allows you to emphasize the packets you are (usually)
608 interested in.
609 </para>
610 <tip>
611 <title>Tip!</title>
612 <para>
613 You will find a lot of Coloring Rule examples at the <command>Wireshark
614 Wiki Coloring Rules page</command> at <ulink
615 url="&WiresharkWikiColoringRulesPage;">&WiresharkWikiColoringRulesPage;</ulink>.
616 </para>
617 </tip>
618 <para>
619 There are two types of coloring rules in Wireshark; temporary ones that are
620 only used until you quit the program, and permanent ones that will be saved to
621 a preference file so that they are available on a next session.
622 </para>
623 <para>
624 Temporary coloring rules can be added by selecting a packet and pressing
625 the <ctrl> key together with one of the number keys. This will
626 create a coloring rule based on the currently selected conversation. It will
627 try to create a conversation filter based on TCP first, then UDP, then IP
628 and at last Ethernet. Temporary filters can also be created by selecting
629 the "Colorize with Filter > Color X" menu items when rightclicking in the
630 packet-detail pane.
631 </para>
633 <para>
634 To permanently colorize packets, select the <command>Coloring Rules...</command> menu item from
635 the <command>View</command> menu; Wireshark will pop up the "Coloring Rules"
636 dialog box as shown in <xref linkend="ChCustColoringRulesDialog"/>.
637 </para>
638 <figure id="ChCustColoringRulesDialog">
639 <title>The "Coloring Rules" dialog box</title>
640 <graphic entityref="WiresharkColoringRulesDialog" format="PNG"/>
641 </figure>
642 <para>
643 Once the Coloring Rules dialog box is up, there are a number
644 of buttons you can use, depending on whether or not you have any
645 color filters installed already.
646 </para>
647 <note><title>Note!</title>
648 <para>
649 You will need to carefully select the order the coloring rules are listed
650 as they are applied in order from top to bottom.
651 So, more specific rules need to be listed before more general rules.
652 For example, if you have a color rule for UDP before the one for DNS,
653 the color rule for DNS will never be applied (as DNS uses UDP, so the
654 UDP rule will match first).
655 </para>
656 </note>
657 <para>
658 If this is the first time you have used Coloring Rules, click on the New
659 button which will bring up the Edit color filter dialog box as shown in
660 <xref linkend="ChCustEditColorDialog"/>.
661 </para>
662 <figure id="ChCustEditColorDialog">
663 <title>The "Edit Color Filter" dialog box</title>
664 <graphic entityref="WiresharkEditColorDialog" format="PNG"/>
665 </figure>
666 <para>
667 In the Edit Color dialog box, simply enter a name for the color filter,
668 and enter a filter string in the Filter text field.
669 <xref linkend="ChCustEditColorDialog"/> shows the values
670 <command>arp</command> and <command>arp</command> which means that
671 the name of the color filter is <command>arp</command> and the filter
672 will select protocols of type <command>arp</command>. Once you have
673 entered these values, you can choose a foreground and background
674 color for packets that match the filter expression. Click on
675 <command>Foreground color...</command> or
676 <command>Background color...</command> to achieve this and
677 Wireshark will pop up the Choose foreground/background color for
678 protocol dialog box as shown in
679 <xref linkend="ChCustChooseColorDialog"/>.
680 </para>
681 <figure id="ChCustChooseColorDialog">
682 <title>The "Choose color" dialog box</title>
683 <graphic entityref="WiresharkChooseColorDialog" format="PNG"/>
684 </figure>
685 <para>
686 Select the color you desire for the selected packets and click on OK.
687 </para>
688 <note>
689 <title>Note!</title>
690 <para>
691 You must select a color in the colorbar next to the colorwheel to
692 load values into the RGB values. Alternatively, you can set the
693 values to select the color you want.
694 </para>
695 </note>
696 <para>
697 <xref linkend="ChCustColorFilterMany"/> shows an example of several color
698 filters being used in Wireshark. You may not like the color choices,
699 however, feel free to choose your own.
700 </para>
701 <para>
702 If you are uncertain which coloring rule actually took place for a
703 specific packet, have a look at the [Coloring Rule Name: ...] and
704 [Coloring Rule String: ...] fields.
705 </para>
706 <figure id="ChCustColorFilterMany">
707 <title>Using color filters with Wireshark</title>
708 <graphic entityref="WiresharkColoringFields" format="PNG"/>
709 </figure>
710 </section>
712 <section id="ChCustProtocolDissectionSection">
713 <title>Control Protocol dissection</title>
714 <para>
715 The user can control how protocols are dissected.
716 </para>
717 <para>
718 Each protocol has its own dissector, so dissecting a complete packet will
719 typically involve several dissectors. As Wireshark tries to find the
720 right dissector for each packet (using static "routes" and heuristics
721 "guessing"), it might choose the wrong dissector in your specific
722 case. For example, Wireshark won't know if you use a common protocol
723 on an uncommon TCP port, e.g. using HTTP on TCP port 800 instead of
724 the standard port 80.
725 </para>
726 <para>
727 There are two ways to control the relations between protocol
728 dissectors: disable a protocol dissector completely or temporarily
729 divert the way Wireshark calls the dissectors.
730 </para>
731 <section id="ChAdvEnabledProtocols"><title>The "Enabled Protocols" dialog
732 box</title>
733 <para>
734 The Enabled Protocols dialog box lets you enable or
735 disable specific protocols; all protocols are enabled by default.
736 When a protocol is disabled, Wireshark stops processing a packet
737 whenever that protocol is encountered.
738 </para>
739 <note><title>Note!</title>
740 <para>
741 Disabling a protocol will prevent information about higher-layer
742 protocols from being displayed. For example,
743 suppose you disabled the IP protocol and selected
744 a packet containing Ethernet, IP, TCP, and HTTP
745 information. The Ethernet information would be
746 displayed, but the IP, TCP and HTTP information
747 would not - disabling IP would prevent it and
748 the other protocols from being displayed.
749 </para>
750 </note>
751 <para>
752 To enable/disable protocols select the <command>Enabled Protocols...</command>
753 item from the <command>Analyze</command> menu; Wireshark will pop up the "Enabled Protocols"
754 dialog box as shown in <xref linkend="ChAdvEnabledProtocolsFig"/>.
755 </para>
756 <figure id="ChAdvEnabledProtocolsFig">
757 <title>The "Enabled Protocols" dialog box</title>
758 <graphic entityref="WiresharkEnabledProtocols" format="PNG"/>
759 </figure>
760 <para>
761 To disable or enable a protocol, simply click on it using the
762 mouse or press the space bar when the protocol is highlighted.
763 Note that typing the first few letters
764 of the protocol name when the Enabled Protocols dialog box is active
765 will temporarily open a search text box and
766 automatically select the first matching protocol name (if it exists).
767 </para>
768 <warning><title>Warning!</title>
769 <para>
770 You have to use the Save button to save your settings. The OK or Apply
771 buttons will not save your changes permanently, so they will be lost
772 when Wireshark is closed.
773 </para>
774 </warning>
775 <para>
776 You can choose from the following actions:
777 <orderedlist>
778 <listitem>
779 <para>
780 <command>Enable All</command>: Enable all protocols in the list.
781 </para>
782 </listitem>
783 <listitem>
784 <para>
785 <command>Disable All</command>: Disable all protocols in the list.
786 </para>
787 </listitem>
788 <listitem>
789 <para>
790 <command>Invert</command>: Toggle the state of all protocols in the
791 list.
792 </para>
793 </listitem>
794 <listitem>
795 <para>
796 <command>OK</command>: Apply the changes and close the dialog box.
797 </para>
798 </listitem>
799 <listitem>
800 <para>
801 <command>Apply</command>: Apply the changes and keep the dialog box
802 open.
803 </para>
804 </listitem>
805 <listitem>
806 <para>
807 <command>Save</command>: Save the settings to the disabled_protos, see
808 <xref linkend="AppFiles"/> for details.
809 </para>
810 </listitem>
811 <listitem>
812 <para>
813 <command>Cancel</command>: Cancel the changes and close the dialog box.
814 </para>
815 </listitem>
816 </orderedlist>
817 </para>
818 </section>
820 <section id="ChAdvDecodeAs"><title>User Specified Decodes</title>
821 <para>
822 The "Decode As" functionality let you temporarily divert specific
823 protocol dissections. This might be useful for example, if you do some
824 uncommon experiments on your network.
825 </para>
826 <para>
827 Decode As is accessed by selecting the <command>Decode As...</command> item from
828 the <command>Analyze</command> menu; Wireshark will pop up the "Decode As"
829 dialog box as shown in <xref linkend="ChAdvDecodeAsFig"/>.
830 </para>
831 <para>
832 <figure id="ChAdvDecodeAsFig">
833 <title>The "Decode As" dialog box</title>
834 <graphic scale="100" entityref="WiresharkDecodeAs" format="PNG"/>
835 </figure>
836 The content of this dialog box depends on the selected packet when it
837 was opened.
838 <warning><title>Warning!</title>
839 <para>
840 These settings will be lost if you quit Wireshark or change profile,
841 unless you save the entries in the <command>Show User Specified Decodes...</command>
842 windows (<xref linkend="ChAdvDecodeAsShow"/>).
843 </para>
844 </warning>
845 <orderedlist>
846 <listitem>
847 <para>
848 <command>Decode</command>: Decode packets the selected way.
849 </para>
850 </listitem>
851 <listitem>
852 <para>
853 <command>Do not decode</command>: Do not decode packets the selected
854 way.
855 </para>
856 </listitem>
857 <listitem>
858 <para>
859 <command>Link/Network/Transport</command>: Specify the network layer
860 at which "Decode As" should take place. Which of these pages are
861 available depends on the content of the selected packet when this
862 dialog box is opened.
863 </para>
864 </listitem>
865 <listitem>
866 <para>
867 <command>Show Current</command>: Open a dialog box showing the
868 current list of user specified decodes.
869 </para>
870 </listitem>
871 <listitem>
872 <para>
873 <command>OK</command>: Apply the currently selected decode and close
874 the dialog box.
875 </para>
876 </listitem>
877 <listitem>
878 <para>
879 <command>Apply</command>: Apply the currently selected decode and keep
880 the dialog box open.
881 </para>
882 </listitem>
883 <listitem>
884 <para>
885 <command>Cancel</command>: Cancel the changes and close the dialog box.
886 </para>
887 </listitem>
888 </orderedlist>
889 </para>
890 </section>
892 <section id="ChAdvDecodeAsShow"><title>Show User Specified Decodes</title>
893 <para>
894 This dialog box shows the currently active user specified decodes. These entries
895 can be saved into current profile for later session.
896 <figure id="ChAdvDecodeAsShowFig">
897 <title>The "Decode As: Show" dialog box</title>
898 <graphic entityref="WiresharkDecodeAsShow" format="PNG"/>
899 </figure>
900 <orderedlist>
901 <listitem>
902 <para>
903 <command>OK</command>: Close this dialog box.
904 </para>
905 </listitem>
906 <listitem>
907 <para>
908 <command>Save</command>: Save the entries in the table into current profile.
909 </para>
910 </listitem>
911 <listitem>
912 <para>
913 <command>Clear</command>: Removes all user specified decodes without updating the profile.
914 </para>
915 </listitem>
916 </orderedlist>
917 </para>
918 </section>
919 </section>
921 <section id="ChCustPreferencesSection"><title>Preferences</title>
922 <para>
923 There are a number of preferences you can set. Simply
924 select the <command>Preferences...</command> menu item from
925 the <command>Edit</command> menu; and Wireshark
926 will pop up the Preferences dialog box as shown in
927 <xref linkend="ChCustGUIPrefPage"/>, with the "User Interface" page as
928 default. On the left side is a tree where you can select the page to be
929 shown.
930 <note><title>Note!</title>
931 <para>
932 Preference settings are added frequently. For a recent explanation of
933 the preference pages and their settings have a look at the
934 <command>Wireshark Wiki Preferences page</command> at <ulink
935 url="&WiresharkWikiPreferencesPage;">&WiresharkWikiPreferencesPage;</ulink>.
936 </para>
937 </note>
938 <warning>
939 <title>Warning!</title>
940 <para>
941 The OK or Apply button will not save the preference settings,
942 you'll have to save the settings by clicking the Save button.
943 </para>
944 </warning>
945 <itemizedlist>
946 <listitem>
947 <para>
948 The <command>OK</command> button will apply the preferences
949 settings and close the dialog.
950 </para>
951 </listitem>
952 <listitem>
953 <para>
954 The <command>Apply</command> button will apply the preferences
955 settings and keep the dialog open.
956 </para>
957 </listitem>
958 <listitem>
959 <para>
960 The <command>Save</command> button will apply the preferences
961 settings, save the settings on the hard disk and keep the dialog open.
962 </para>
963 </listitem>
964 <listitem>
965 <para>
966 The <command>Cancel</command> button will restore all preferences
967 settings to the last saved state.
968 </para>
969 </listitem>
970 </itemizedlist>
971 </para>
972 <figure id="ChCustGUIPrefPage">
973 <title>The preferences dialog box</title>
974 <graphic entityref="WiresharkGUIPreferences" format="PNG"/>
975 </figure>
977 <section id="ChCustInterfaceOptionsSection"><title>Interface Options</title>
978 <para>
979 In the Capture preferences it is possible to configure several options for the interfaces
980 available on your computer. Select the <command>Capture</command> pane and press the
981 Interfaces: <command>Edit</command> button. In this window it is possible to change the
982 default link-layer header type for the interface, add a comment or choose to hide a
983 interface from other parts of the program.
984 </para>
985 <figure id="ChCustInterfaceOptionsPage">
986 <title>The interface options dialog box</title>
987 <graphic entityref="WiresharkGUIInterfaceOptions" format="PNG"/>
988 </figure>
989 <para>Each row contains options for each interface available on your computer.</para>
990 <itemizedlist>
991 <listitem>
992 <para><command>Device</command>: the device name provided by the operating system.</para>
993 </listitem>
994 <listitem>
995 <para><command>Description</command>: provided by the operating system.</para>
996 </listitem>
997 <listitem>
998 <para><command>Default link-layer</command>: each interface may provide several
999 link-layer header types. The default link-layer chosen here is the one used when you
1000 first start Wireshark. It is also possible to change this value in
1001 <xref linkend="ChCapCaptureOptions"/> when you start a capture.
1002 For a detailed description, see <xref linkend="ChCapLinkLayerHeader"/>.</para>
1003 </listitem>
1004 <listitem>
1005 <para><command>Comment</command>: a user provided description of the interface.
1006 This comment will be used as a description instead of the operating system
1007 description.</para>
1008 </listitem>
1009 <listitem>
1010 <para><command>Hide?</command>: enable this option to hide the interface from other
1011 parts of the program.</para>
1012 </listitem>
1013 </itemizedlist>
1014 </section>
1015 </section>
1017 <section id="ChCustConfigProfilesSection"><title>Configuration Profiles</title>
1018 <para>
1019 Configuration Profiles can be used to configure and use more than one set of preferences
1020 and configurations. Select the <command>Configuration Profiles...</command> menu item from
1021 the <command>Edit</command> menu, or simply press Shift-Ctrl-A; and Wireshark will pop up the
1022 Configuration Profiles dialog box as shown in <xref linkend="ChCustGUIConfigProfilesPage"/>.
1023 It is also possible to click in the "Profile" part of the statusbar to popup a menu with
1024 available Configuration Profiles (<xref linkend="ChUseWiresharkStatusbarProfile"/>).
1025 </para>
1026 <para>
1027 Configuration files stored in the Profiles:
1028 <itemizedlist>
1029 <listitem>
1030 <para>
1031 Preferences (preferences) (<xref linkend="ChCustPreferencesSection"/>)
1032 </para>
1033 </listitem>
1034 <listitem>
1035 <para>
1036 Capture Filters (cfilters) (<xref linkend="ChWorkDefineFilterSection"/>)
1037 </para>
1038 </listitem>
1039 <listitem>
1040 <para>
1041 Display Filters (dfilters) (<xref linkend="ChWorkDefineFilterSection"/>)
1042 </para>
1043 </listitem>
1044 <listitem>
1045 <para>
1046 Coloring Rules (colorfilters) (<xref linkend="ChCustColorizationSection"/>)
1047 </para>
1048 </listitem>
1049 <listitem>
1050 <para>
1051 Disabled Protocols (disabled_protos) (<xref linkend="ChAdvEnabledProtocols"/>)
1052 </para>
1053 </listitem>
1054 <listitem>
1055 <para>
1056 User Accessible Tables:
1057 <itemizedlist>
1058 <listitem>
1059 <para>
1060 Custom HTTP headers (custom_http_header_fields)
1061 </para>
1062 </listitem>
1063 <listitem>
1064 <para>
1065 Custom IMF headers (imf_header_fields)
1066 </para>
1067 </listitem>
1068 <listitem>
1069 <para>
1070 Custom LDAP AttributeValue types (custom_ldap_attribute_types)
1071 </para>
1072 </listitem>
1073 <listitem>
1074 <para>
1075 Display Filter Macros (dfilter_macros) (<xref linkend="ChDisplayFilterMacrosSection"/>)
1076 </para>
1077 </listitem>
1078 <listitem>
1079 <para>
1080 ESS Category Attributes (ess_category_attributes) (<xref linkend="ChEssCategoryAttributes"/>)
1081 </para>
1082 </listitem>
1083 <listitem>
1084 <para>
1085 GeoIP Database Paths (geoip_db_paths) (<xref linkend="ChGeoIPDbPaths"/>)
1086 </para>
1087 </listitem>
1088 <listitem>
1089 <para>
1090 K12 Protocols (k12_protos) (<xref linkend="ChK12ProtocolsSection"/>)
1091 </para>
1092 </listitem>
1093 <listitem>
1094 <para>
1095 Object Identifier Names and Associated Syntaxes (<xref linkend="ChObjectIdentifiers"/>)
1096 </para>
1097 </listitem>
1098 <listitem>
1099 <para>
1100 PRES Users Context List (pres_context_list) (<xref linkend="ChPresContextList"/>)
1101 </para>
1102 </listitem>
1103 <listitem>
1104 <para>
1105 SCCP Users Table (sccp_users) (<xref linkend="ChSccpUsers"/>)
1106 </para>
1107 </listitem>
1108 <listitem>
1109 <para>
1110 SNMP Enterprise Specific Trap Types (snmp_specific_traps) (<xref linkend="ChSNMPEnterpriseSpecificTrapTypes"/>)
1111 </para>
1112 </listitem>
1113 <listitem>
1114 <para>
1115 SNMP Users (snmp_users) (<xref linkend="ChSNMPUsersSection"/>)
1116 </para>
1117 </listitem>
1118 <listitem>
1119 <para>
1120 User DLTs Table (user_dlts) (<xref linkend="ChUserDLTsSection"/>)
1121 </para>
1122 </listitem>
1123 <listitem>
1124 <para>
1125 IKEv2 decryption table (ikev2_decryption_table) (<xref linkend="ChIKEv2DecryptionSection"/>)
1126 </para>
1127 </listitem>
1128 </itemizedlist>
1129 </para>
1130 </listitem>
1131 <listitem>
1132 <para>
1133 Changed dissector assignments (decode_as_entries), which can be set in <command>Decode As...</command>
1134 dialog box (<xref linkend="ChAdvDecodeAs"/>), and further saved in the <command>User Specified Decodes...</command>
1135 window (<xref linkend="ChAdvDecodeAsShow"/>).
1136 </para>
1137 </listitem>
1138 <listitem>
1139 <para>
1140 Some recent settings (recent), such as pane sizes in the Main window
1141 (<xref linkend="ChUseMainWindowSection"/>), column widths in the packet list
1142 (<xref linkend="ChUsePacketListPaneSection"/>), all selections in the "View" menu
1143 (<xref linkend="ChUseViewMenuSection"/>) and the last directory navigated to in the
1144 File Open dialog.
1145 </para>
1146 </listitem>
1147 </itemizedlist>
1148 <note><title>Other configurations</title>
1149 <para>
1150 All other configurations are stored in the personal configuration folder,
1151 and are common to all profiles.
1152 </para>
1153 </note>
1154 </para>
1155 <figure id="ChCustGUIConfigProfilesPage">
1156 <title>The configuration profiles dialog box</title>
1157 <graphic entityref="WiresharkGUIConfigProfiles" format="PNG"/>
1158 </figure>
1159 <para>
1160 <variablelist>
1161 <varlistentry><term><command>New</command></term>
1162 <listitem>
1163 <para>
1164 This button adds a new profile to the profiles list. The name of the
1165 created profile is "New profile" and can be changed in the Properties field.
1166 </para>
1167 </listitem>
1168 </varlistentry>
1169 <varlistentry><term><command>Copy</command></term>
1170 <listitem>
1171 <para>
1172 This button adds a new profile to the profiles list, copying all configuration
1173 from the profile currently selected in the list. The name of the created
1174 profile is the same as the copied profile, with the text "(copy)" applied.
1175 The name can be changed in the Properties field.
1176 </para>
1177 </listitem>
1178 </varlistentry>
1179 <varlistentry><term><command>Delete</command></term>
1180 <listitem>
1181 <para>
1182 This button deletes the selected profile, including all configuration
1183 files used in this profile. It is not possible to delete the "Default" profile.
1184 </para>
1185 </listitem>
1186 </varlistentry>
1187 <varlistentry><term><command>Configuration Profiles</command></term>
1188 <listitem>
1189 <para>
1190 You can select a configuration profile from this list (which will fill
1191 in the profile name in the fields down at the bottom of the dialog box).
1192 </para>
1193 </listitem>
1194 </varlistentry>
1195 <varlistentry><term><command>Profile name:</command></term>
1196 <listitem>
1197 <para>
1198 You can change the name of the currently selected profile here.
1199 </para>
1200 <note><title>Used as a folder name</title>
1201 <para>
1202 The profile name will be used as a folder name in the configured
1203 "Personal configurations" folder. If adding multiple profiles with the
1204 same name, only one profile will be created.
1205 </para>
1206 </note>
1207 <note><title>Illegal characters</title>
1208 <para>
1209 On Windows the profile name cannot start or end with a period (.), and cannot contain
1210 any of the following characters: <command>\ / : * ? " < > |</command>
1211 </para>
1212 <para>
1213 On Unix the profile name cannot contain the '<command>/</command>' character.
1214 </para>
1215 </note>
1216 </listitem>
1217 </varlistentry>
1218 <varlistentry><term><command>OK</command></term>
1219 <listitem>
1220 <para>
1221 This button saves all changes, applies the selected profile and closes the dialog.
1222 </para>
1223 </listitem>
1224 </varlistentry>
1225 <varlistentry><term><command>Apply</command></term>
1226 <listitem>
1227 <para>
1228 This button saves all changes, applies the selected profile and keeps the dialog open.
1229 </para>
1230 </listitem>
1231 </varlistentry>
1232 <varlistentry><term><command>Cancel</command></term>
1233 <listitem>
1234 <para>
1235 Close this dialog. This will discard unsaved settings, new profiles will not be added
1236 and deleted profiles will not be deleted.
1237 </para>
1238 </listitem>
1239 </varlistentry>
1240 <varlistentry><term><command>Help</command></term>
1241 <listitem>
1242 <para>
1243 Show this help page.
1244 </para>
1245 </listitem>
1246 </varlistentry>
1247 </variablelist>
1248 </para>
1249 </section>
1250 <section id="ChUserTable"><title>User Table</title>
1251 <para>
1252 The User Table editor is used for managing various tables in wireshark. Its main dialog works
1253 very similarly to that of <xref linkend="ChCustColorizationSection"/>.
1254 </para>
1255 </section>
1258 <section id="ChDisplayFilterMacrosSection"><title>Display Filter Macros</title>
1259 <para>
1260 Display Filter Macros are a mechanism to create shortcuts for complex filters. For example defining a
1261 display filter macro named <command>tcp_conv</command> whose text is
1262 <command> ( (ip.src == $1 and ip.dst == $2 and tcp.srcport == $3 and tcp.dstport == $4) or
1263 (ip.src == $2 and ip.dst == $1 and tcp.srcport == $4 and tcp.dstport == $3) ) </command>
1264 would allow to use a display filter like <command>${tcp_conv:10.1.1.2;10.1.1.3;1200;1400}</command>
1265 instead of typing the whole filter.
1266 </para>
1267 <para>
1268 Display Filter Macros can be managed with a <xref linkend="ChUserTable"/> by selecting
1269 <command>Analyze → Display Filter Macros</command> from the menu.
1270 The User Table has the following fields
1271 </para>
1272 <variablelist>
1273 <varlistentry><term><command>Name</command></term>
1274 <listitem>
1275 <para>
1276 The name of the macro.
1277 </para>
1278 </listitem>
1279 </varlistentry>
1280 <varlistentry><term><command>Text</command></term>
1281 <listitem>
1282 <para>
1283 The replacement text for the macro it uses $1, $2, $3, ... as the input arguments.
1284 </para>
1285 </listitem>
1286 </varlistentry>
1287 </variablelist>
1289 </section>
1292 <section id="ChEssCategoryAttributes"><title>ESS Category Attributes</title>
1293 <para>
1294 Wireshark uses this table to map ESS Security Category attributes to textual
1295 representations. The values to put in this table are usually found in a
1296 <ulink url="http://www.xmlspif.org/">XML SPIF</ulink>, which is used for defining
1297 security labels.
1298 </para>
1299 <para>
1300 This table is handled by an <xref linkend="ChUserTable"/> with the following fields.
1301 </para>
1302 <variablelist>
1303 <varlistentry><term><command>Tag Set</command></term>
1304 <listitem>
1305 <para>
1306 An Object Identifier representing the Category Tag Set.
1307 </para>
1308 </listitem>
1309 </varlistentry>
1310 <varlistentry><term><command>Value</command></term>
1311 <listitem>
1312 <para>
1313 The value (Label And Cert Value) representing the Category.
1314 </para>
1315 </listitem>
1316 </varlistentry>
1317 <varlistentry><term><command>Name</command></term>
1318 <listitem>
1319 <para>
1320 The textual representation for the value.
1321 </para>
1322 </listitem>
1323 </varlistentry>
1324 </variablelist>
1325 </section>
1327 <section id="ChGeoIPDbPaths"><title>GeoIP Database Paths</title>
1328 <para>
1329 If your copy of Wireshark supports <ulink url="http://www.maxmind.com/">MaxMind's</ulink> 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 <ulink url="http://www.maxmind.com/download/geoip/database/">available at no cost</ulink>, while others require a licensing fee. See <ulink url="http://www.maxmind.com/app/ip-location">the MaxMind web site</ulink> for more information.
1330 </para>
1331 <para>
1332 This table is handled by an <xref linkend="ChUserTable"/> with the following fields.
1333 </para>
1334 <variablelist>
1335 <varlistentry><term><command>Database pathname</command></term>
1336 <listitem>
1337 <para>
1338 This specifies a directory containing GeoIP data files. Any files
1339 beginning with <filename>Geo</filename> and ending with
1340 <filename>.dat</filename> will be automatically loaded. A total of 8
1341 files can be loaded.
1342 </para>
1343 <para>
1344 The locations for your data files are up to you, but <filename class='directory'>/usr/share/GeoIP</filename> (Linux), <filename class='directory'>C:\GeoIP</filename> (Windows), <filename class='directory'>C:\Program Files\Wireshark\GeoIP</filename> (Windows) might be good choices.
1345 </para>
1346 </listitem>
1347 </varlistentry>
1348 </variablelist>
1349 </section>
1351 <section id="ChIKEv2DecryptionSection"><title>IKEv2 decryption table</title>
1352 <para>
1353 Wireshark can decrypt Encrypted Payloads of IKEv2 (Internet Key Exchange version 2) packets if necessary information is provided.
1354 Note that you can decrypt only IKEv2 packets with this feature. If you want to decrypt IKEv1 packets or ESP packets,
1355 use Log Filename setting under ISAKMP protocol preference or settings under ESP protocol preference respectively.
1356 </para>
1357 <para>
1358 This table is handled by an <xref linkend="ChUserTable"/> with the following fields.
1359 </para>
1360 <variablelist>
1361 <varlistentry><term><command>Initiator's SPI</command></term>
1362 <listitem>
1363 <para>
1364 Initiator's SPI of the IKE_SA. This field takes hexadecimal string without "0x" prefix
1365 and the length must be 16 hex chars (represents 8 octets).
1366 </para>
1367 </listitem>
1368 </varlistentry>
1369 <varlistentry><term><command>Responder's SPI</command></term>
1370 <listitem>
1371 <para>
1372 Responder's SPI of the IKE_SA. This field takes hexadecimal string without "0x" prefix
1373 and the length must be 16 hex chars (represents 8 octets).
1374 </para>
1375 </listitem>
1376 </varlistentry>
1377 <varlistentry><term><command>SK_ei</command></term>
1378 <listitem>
1379 <para>
1380 Key used to encrypt/decrypt IKEv2 packets from initiator to responder.
1381 This field takes hexadecimal string without "0x" prefix and its length
1382 must meet the requirement of the encryption algorithm selected.
1383 </para>
1384 </listitem>
1385 </varlistentry>
1386 <varlistentry><term><command>SK_er</command></term>
1387 <listitem>
1388 <para>
1389 Key used to encrypt/decrypt IKEv2 packets from responder to initiator.
1390 This field takes hexadecimal string without "0x" prefix and its length
1391 must meet the requirement of the encryption algorithm selected.
1392 </para>
1393 </listitem>
1394 </varlistentry>
1395 <varlistentry><term><command>Encryption Algorithm</command></term>
1396 <listitem>
1397 <para>
1398 Encryption algorithm of the IKE_SA.
1399 </para>
1400 </listitem>
1401 </varlistentry>
1402 <varlistentry><term><command>SK_ai</command></term>
1403 <listitem>
1404 <para>
1405 Key used to calculate Integrity Checksum Data for IKEv2 packets from responder to initiator.
1406 This field takes hexadecimal string without "0x" prefix and its length
1407 must meet the requirement of the integrity algorithm selected.
1408 </para>
1409 </listitem>
1410 </varlistentry>
1411 <varlistentry><term><command>SK_ar</command></term>
1412 <listitem>
1413 <para>
1414 Key used to calculate Integrity Checksum Data for IKEv2 packets from initiator to responder.
1415 This field takes hexadecimal string without "0x" prefix and its length
1416 must meet the requirement of the integrity algorithm selected.
1417 </para>
1418 </listitem>
1419 </varlistentry>
1420 <varlistentry><term><command>Integrity Algorithm</command></term>
1421 <listitem>
1422 <para>
1423 Integrity algorithm of the IKE_SA.
1424 </para>
1425 </listitem>
1426 </varlistentry>
1428 </variablelist>
1429 </section>
1431 <section id="ChObjectIdentifiers"><title>Object Identifiers</title>
1432 <para>
1433 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.
1434 </para>
1435 <para>
1436 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.
1437 </para>
1438 <para>
1439 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").
1440 </para>
1441 <para>
1442 This table is handled by an <xref linkend="ChUserTable"/> with the following fields.
1443 </para>
1444 <variablelist>
1445 <varlistentry><term><command>OID</command></term>
1446 <listitem>
1447 <para>
1448 The string representation of the Object Identifier e.g. "2.5.4.6".
1449 </para>
1450 </listitem>
1451 </varlistentry>
1452 <varlistentry><term><command>Name</command></term>
1453 <listitem>
1454 <para>
1455 The name that should be displayed by Wireshark when the Object Identifier is dissected e.g. ("c");
1456 </para>
1457 </listitem>
1458 </varlistentry>
1459 <varlistentry><term><command>Syntax</command></term>
1460 <listitem>
1461 <para>
1462 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").
1463 </para>
1464 </listitem>
1465 </varlistentry>
1466 </variablelist>
1467 </section>
1469 <section id="ChPresContextList"><title>PRES Users Context List</title>
1470 <para>
1471 Wireshark uses this table to map a presentation context identifier to a given object identifier when the
1472 capture does not contain a PRES package with a presentation context definition list for the conversation.
1473 </para>
1474 <para>
1475 This table is handled by an <xref linkend="ChUserTable"/> with the following fields.
1476 </para>
1477 <variablelist>
1478 <varlistentry><term><command>Context Id</command></term>
1479 <listitem>
1480 <para>
1481 An Integer representing the presentation context identifier for which this association is valid.
1482 </para>
1483 </listitem>
1484 </varlistentry>
1485 <varlistentry><term><command>Syntax Name OID</command></term>
1486 <listitem>
1487 <para>
1488 The object identifier representing the abstract syntax name, which defines the protocol that is
1489 carried over this association.
1490 </para>
1491 </listitem>
1492 </varlistentry>
1493 </variablelist>
1494 </section>
1497 <section id="ChSccpUsers"><title>SCCP users Table</title>
1498 <para>
1499 Wireshark uses this table to map specific protocols to a certain DPC/SSN combination for SCCP.
1500 </para>
1501 <para>
1502 This table is handled by an <xref linkend="ChUserTable"/> with the following fields.
1503 </para>
1504 <variablelist>
1505 <varlistentry><term><command>Network Indicator</command></term>
1506 <listitem>
1507 <para>
1508 An Integer representing the network indicator for which this association is valid.
1509 </para>
1510 </listitem>
1511 </varlistentry>
1513 <varlistentry><term><command>Called DPCs</command></term>
1514 <listitem>
1515 <para>
1516 An range of integers representing the dpcs for which this association is valid.
1517 </para>
1518 </listitem>
1519 </varlistentry>
1521 <varlistentry><term><command>Called SSNs</command></term>
1522 <listitem>
1523 <para>
1524 An range of integers representing the ssns for which this association is valid.
1525 </para>
1526 </listitem>
1527 </varlistentry>
1529 <varlistentry><term><command>User protocol</command></term>
1530 <listitem>
1531 <para>
1532 The protocol that is carried over this association
1533 </para>
1534 </listitem>
1535 </varlistentry>
1538 </variablelist>
1539 </section>
1542 <section id="ChSNMPSMIModules"><title>SMI (MIB and PIB) Modules</title>
1543 <para>
1544 If your copy of Wireshark supports libSMI, you can specify a list of MIB
1545 and PIB modules here. The COPS and SNMP dissectors can use them to resolve
1546 OIDs.
1547 </para>
1548 <variablelist>
1549 <varlistentry><term><command>Module name</command></term>
1550 <listitem>
1551 <para>
1552 The name of the module, e.g. <database>IF-MIB</database>.
1553 </para>
1554 </listitem>
1555 </varlistentry>
1556 </variablelist>
1557 </section>
1560 <section id="ChSNMPSMIPaths"><title>SMI (MIB and PIB) Paths</title>
1561 <para>
1562 If your copy of Wireshark supports libSMI, you can specify one or more
1563 paths to MIB and PIB modules here.
1564 </para>
1565 <variablelist>
1566 <varlistentry><term><command>Directory name</command></term>
1567 <listitem>
1568 <para>
1569 A module directory, e.g. <filename
1570 class='directory'>/usr/local/snmp/mibs</filename>. Wireshark
1571 automatically uses the standard SMI path for your system, so you
1572 usually don't have to add anything here.
1573 </para>
1574 </listitem>
1575 </varlistentry>
1576 </variablelist>
1577 </section>
1580 <section id="ChSNMPEnterpriseSpecificTrapTypes"><title>SNMP Enterprise Specific Trap Types</title>
1581 <para>
1582 Wireshark uses this table to map specific-trap values to user defined descriptions in a Trap PDU.
1583 The description is shown in the packet details specific-trap element.
1584 </para>
1585 <para>
1586 This table is handled by an <xref linkend="ChUserTable"/> with the following fields.
1587 </para>
1588 <variablelist>
1589 <varlistentry><term><command>Enterprise OID</command></term>
1590 <listitem>
1591 <para>
1592 The object identifier representing the object generating the trap.
1593 </para>
1594 </listitem>
1595 </varlistentry>
1596 <varlistentry><term><command>Trap Id</command></term>
1597 <listitem>
1598 <para>
1599 An Integer representing the specific-trap code.
1600 </para>
1601 </listitem>
1602 </varlistentry>
1603 <varlistentry><term><command>Description</command></term>
1604 <listitem>
1605 <para>
1606 The description to show in the packet details.
1607 </para>
1608 </listitem>
1609 </varlistentry>
1610 </variablelist>
1611 </section>
1613 <section id="ChSNMPUsersSection"><title>SNMP users Table</title>
1614 <para>
1615 Wireshark uses this table to verify authentication and to decrypt encrypted SNMPv3 packets.
1616 </para>
1617 <para>
1618 This table is handled by an <xref linkend="ChUserTable"/> with the following fields.
1619 </para>
1620 <variablelist>
1621 <varlistentry><term><command>Engine ID</command></term>
1622 <listitem>
1623 <para>
1624 If given this entry will be used only for packets whose engine id is this.
1625 This field takes an hexadecimal string in the form 0102030405.
1626 </para>
1627 </listitem>
1628 </varlistentry>
1629 <varlistentry><term><command>Username</command></term>
1630 <listitem>
1631 <para>
1632 This is the userName. When a single user has more than one password
1633 for different SNMP-engines the first entry to match both is taken, if you
1634 need a catch all engine-id (empty) that entry should be the last one.
1635 </para>
1636 </listitem>
1637 </varlistentry>
1638 <varlistentry><term><command>Authentication model</command></term>
1639 <listitem>
1640 <para>
1641 Which auth model to use (either "MD5" or "SHA1").
1642 </para>
1643 </listitem>
1644 </varlistentry>
1645 <varlistentry><term><command>Password</command></term>
1646 <listitem>
1647 <para>
1648 The authentication password. Use '\xDD' for unprintable characters.
1649 An hexadecimal password must be entered as a sequence of '\xDD' characters.
1650 For example the hex password 010203040506 must be entered as '\x01\x02\x03\x04\x05\x06'.
1651 The '\' character must be treated as an unprintable character, i.e.
1652 it must be entered as '\x5C' or '\x5c'.
1653 </para>
1654 </listitem>
1655 </varlistentry>
1656 <varlistentry><term><command>Privacy protocol</command></term>
1657 <listitem>
1658 <para>
1659 Which encryption algorithm to use (either "DES" or "AES").
1660 </para>
1661 </listitem>
1662 </varlistentry>
1663 <varlistentry><term><command>Privacy password</command></term>
1664 <listitem>
1665 <para>
1666 The privacy password. Use '\xDD' for unprintable characters.
1667 An hexadecimal password must be entered as a sequence of '\xDD' characters.
1668 For example the hex password 010203040506 must be entered as '\x01\x02\x03\x04\x05\x06'.
1669 The '\' character must be treated as an unprintable character, i.e.
1670 it must be entered as '\x5C' or '\x5c'.
1671 </para>
1672 </listitem>
1673 </varlistentry>
1674 </variablelist>
1675 </section>
1677 <section id="ChK12ProtocolsSection"><title>Tektronix K12xx/15 RF5 protocols Table</title>
1678 <para>
1679 The Tektronix K12xx/15 rf5 file format uses helper files (*.stk) to identify the various protocols that are
1680 used by a certain interface. Wireshark doesn't read these stk files, it uses a table that helps it identify
1681 which lowest layer protocol to use.
1682 </para>
1683 <para>
1684 Stk file to protocol matching is handled by an <xref linkend="ChUserTable"/> with the following fields.
1685 </para>
1686 <variablelist>
1687 <varlistentry><term><command>Match string</command></term>
1688 <listitem>
1689 <para>
1690 A partial match for an stk filename, the first match wins, so if you have a specific case and a
1691 general one the specific one must appear first in the list.
1692 </para>
1693 </listitem>
1694 </varlistentry>
1695 <varlistentry><term><command>Protocol</command></term>
1696 <listitem>
1697 <para>
1698 This is the name of the encapsulating protocol (the lowest layer in the packet data) it can be either
1699 just the name of the protocol (e.g. mtp2, eth_witoutfcs, sscf-nni ) or the name of the encapsulation
1700 protocol and the "application" protocol over it separated by a colon (e.g sscop:sscf-nni, sscop:alcap, sscop:nbap, ...)
1701 </para>
1702 </listitem>
1703 </varlistentry>
1704 </variablelist>
1705 </section>
1707 <section id="ChUserDLTsSection"><title>User DLTs protocol table</title>
1708 <para>
1709 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.
1710 </para>
1711 <para>
1712 This table is handled by an <xref linkend="ChUserTable"/> with the following fields.
1713 </para>
1714 <variablelist>
1715 <varlistentry><term><command>DLT</command></term>
1716 <listitem>
1717 <para>
1718 One of the user dlts.
1719 </para>
1720 </listitem>
1721 </varlistentry>
1722 <varlistentry><term><command>Payload protocol</command></term>
1723 <listitem>
1724 <para>
1725 This is the name of the payload protocol (the lowest layer in the packet data). (e.g. "eth" for ethernet, "ip" for IPv4)
1726 </para>
1727 </listitem>
1728 </varlistentry>
1729 <varlistentry><term><command>Header size</command></term>
1730 <listitem>
1731 <para>
1732 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.
1733 </para>
1734 </listitem>
1735 </varlistentry>
1736 <varlistentry><term><command>Header protocol</command></term>
1737 <listitem>
1738 <para>
1739 The name of the header protocol to be used (uses "data" as default).
1740 </para>
1741 </listitem>
1742 </varlistentry>
1743 <varlistentry><term><command>Trailer size</command></term>
1744 <listitem>
1745 <para>
1746 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.
1747 </para>
1748 </listitem>
1749 </varlistentry>
1750 <varlistentry><term><command>Trailer protocol</command></term>
1751 <listitem>
1752 <para>
1753 The name of the trailer protocol to be used (uses "data" as default).
1754 </para>
1755 </listitem>
1756 </varlistentry>
1758 </variablelist>
1759 </section>
1761 </chapter>
1762 <!-- End of WSUG Chapter Customizing -->