628883fe1aedf8ceff08d6c06c05a8faf68173a6
[obnox/wireshark/wip.git] / doc / ethereal.pod.template
1
2 =head1 NAME
3
4 ethereal - Interactively browse network traffic
5
6 =head1 SYNOPSYS
7
8 B<ethereal>
9 S<[ B<-B> byte view height ]>
10 S<[ B<-c> count ]>
11 S<[ B<-f> capture filter expression ]>
12 S<[ B<-h> ]>
13 S<[ B<-i> interface ]> 
14 S<[ B<-k> ]>
15 S<[ B<-l> ]>
16 S<[ B<-m> font ]>
17 S<[ B<-n> ]>
18 S<[ B<-N> resolving flags ] ...>
19 S<[ B<-o> preference setting ] ...>
20 S<[ B<-p> ]>
21 S<[ B<-P> packet list height ]>
22 S<[ B<-Q> ]>
23 S<[ B<-r> infile ]>
24 S<[ B<-R> display filter expression ]>
25 S<[ B<-S> ]>
26 S<[ B<-s> snaplen ]>
27 S<[ B<-T> tree view height ]>
28 S<[ B<-t> time stamp format ]>
29 S<[ B<-v> ]>
30 S<[ B<-w> savefile]>
31
32 =head1 DESCRIPTION
33
34 B<Ethereal> is a GUI network protocol analyzer.  It lets you
35 interactively browse packet data from a live network or from a
36 previously saved capture file.  B<Ethereal> knows how to read B<libpcap>
37 capture files, including those of B<tcpdump>.  In addition, B<Ethereal>
38 can read capture files from B<snoop> (including B<Shomiti>) and
39 B<atmsnoop>, B<LanAlyzer>, B<Sniffer> (compressed or uncompressed),
40 Microsoft B<Network Monitor>, AIX's B<iptrace>, B<NetXray>, B<Sniffer
41 Pro>, B<Etherpeek>, B<RADCOM>'s WAN/LAN analyzer, B<Lucent/Ascend>
42 router debug output, HP-UX's B<nettl>, the dump output from B<Toshiba's>
43 ISDN routers, the output from B<i4btrace> from the ISDN4BSD project, the
44 output in B<IPLog> format from the Cisco Secure Intrusion Detection
45 System, B<pppd logs> (pppdump format), the output from VMS's
46 B<TCPIPtrace> utility, and the text output from the B<DBS Etherwatch>
47 VMS utility.  There is no need to tell B<Ethereal> what type of file you
48 are reading; it will determine the file type by itself.  B<Ethereal> is
49 also capable of reading any of these file formats if they are compressed
50 using gzip.  B<Ethereal> recognizes this directly from the file; the
51 '.gz' extension is not required for this purpose.
52
53 Like other protocol analyzers, B<Ethereal>'s main window shows 3 views
54 of a packet.  It shows a summary line, briefly describing what the
55 packet is.  A protocol tree is shown, allowing you to drill down to
56 exact protocol or field that you interested in.  Finally, a hex dump
57 shows you exactly what the packet looks like when it goes over the wire.
58
59 In addition, B<Ethereal> has some features that make it unique.  It can
60 assemble all the packets in a TCP conversation and show you the ASCII
61 (or EBCDIC, or hex) data in that conversation.  Display filters in
62 B<Ethereal> are very powerful; more fields are filterable in B<Ethereal>
63 than in other protocol analyzers, and the syntax you can use to create
64 your filters is richer.  As B<Ethereal> progresses, expect more and more
65 protocol fields to be allowed in display filters.
66
67 Packet capturing is performed with the pcap library.  The capture filter
68 syntax follows the rules of the pcap library.  This syntax is different
69 from the display filter syntax.
70
71 Compressed file support uses (and therefore requires) the zlib library. 
72 If the zlib library is not present, B<Ethereal> will compile, but will
73 be unable to read compressed files.
74
75 =head1 OPTIONS
76
77 =over 4
78
79 =item -B
80
81 Sets the initial height of the byte view (bottom) pane.
82
83 =item -c
84
85 Sets the default number of packets to read when capturing live
86 data.
87
88 =item -f
89
90 Sets the capture filter expression.
91
92 =item -h
93
94 Prints the version and options and exits.
95
96 =item -i
97
98 Sets the name of the network interface or pipe to use for live packet capture.
99 Network interface names should match one of the names listed in "B<netstat -i>"
100 or "B<ifconfig -a>".
101 Pipe names should be either the name of a FIFO (named pipe) or ``-'' to read
102 data from the standard input. Data read from pipes must be in libpcap format.
103
104 =item -k
105
106 Starts the capture session immediately.  If the B<-i> flag was
107 specified, the capture uses the specified interface.  Otherwise,
108 B<Ethereal> searches the list of interfaces, choosing the first
109 non-loopback interface if there are any non-loopback interfaces, and
110 choosing the first loopback interface if there are no non-loopback
111 interfaces; if there are no interfaces, B<Ethereal> reports an error and
112 doesn't start the capture.
113
114 =item -l
115
116 Turns on automatic scrolling if the packet display is being updated
117 automatically as packets arrive during a capture (as specified by the
118 B<-S> flag).
119
120 =item -m
121
122 Sets the name of the font used by B<Ethereal> for most text. 
123 B<Ethereal> will construct the name of the bold font used for the data
124 in the byte view pane that corresponds to the field selected in the
125 protocol tree pane from the name of the main text font.
126
127 =item -n
128
129 Disables network object name resolution (such as hostname, TCP and UDP port
130 names).
131
132 =item -N
133
134 Turns on name resolving for particular types of addresses and port
135 numbers; the argument is a string that may contain the letters B<m> to
136 enable MAC address resolution, B<n> to enable network address
137 resolution, and B<t> to enable transport-layer port number resolution. 
138 This overrides B<-n> if both B<-N> and B<-n> are present.
139
140 =item -o
141
142 Sets a preference value, overriding the default value and any value read
143 from a preference file.  The argument to the flag is a string of the
144 form I<prefname>B<:>I<value>, where I<prefname> is the name of the
145 preference (which is the same name that would appear in the preference
146 file), and I<value> is the value to which it should be set.
147
148 =item -p
149
150 I<Don't> put the interface into promiscuous mode.  Note that the
151 interface might be in promiscuous mode for some other reason; hence,
152 B<-p> cannot be used to ensure that the only traffic that is captured is
153 traffic sent to or from the machine on which B<Ethereal> is running,
154 broadcast traffic, and multicast traffic to addresses received by that
155 machine.
156
157 =item -P
158
159 Sets the initial height of the packet list (top) pane.
160
161 =item -Q
162
163 Causes B<Ethereal> to exit after the end of capture session (useful in
164 batch mode with B<-c> option for instance); this option requires the
165 B<-i> and B<-w> parameters.
166
167 =item -r
168
169 Reads packet data from I<file>.
170
171 =item -R
172
173 When reading a capture file specified with the B<-r> flag, causes the
174 specified filter (which uses the syntax of display filters, rather than
175 that of capture filters) to be applied to all packets read from the
176 capture file; packets not matching the filter are discarded.
177
178 =item -S
179
180 Specifies that the live packet capture will be performed in a separate
181 process, and that the packet display will automatically be updated as
182 packets are seen.
183
184 =item -s
185
186 Sets the default snapshot length to use when capturing live data. 
187 No more than I<snaplen> bytes of each network packet will be read into
188 memory, or saved to disk.
189
190 =item -T
191
192 Sets the initial height of the tree view (middle) pane.
193
194 =item -t
195
196 Sets the format of the packet timestamp displayed in the packet list
197 window.  The format can be one of 'r' (relative), 'a' (absolute), 'ad'
198 (absolute with date), or 'd' (delta).  The relative time is the time
199 elapsed between the first packet and the current packet.  The absolute
200 time is the actual time the packet was captured, with no date displayed;
201 the absolute date and time is the actual time and date the packet was
202 captured.  The delta time is the time since the previous packet was
203 captured.  The default is relative.
204
205 =item -v
206
207 Prints the version and exits.
208
209 =item -w
210
211 Sets the default capture file name.
212
213 =back
214
215 =head1 INTERFACE
216
217 =head2 MENU ITEMS
218
219 =over 4
220
221 =item File:Open, File:Close, File:Reload
222
223 Open, close, or reload a capture file.  The I<File:Open> dialog box
224 allows a filter to be specified; when the capture file is read, the
225 filter is applied to all packets read from the file, and packets not
226 matching the filter are discarded.
227
228 =item File:Save, File:Save As
229
230 Save the current capture, or the packets currently displayed from that
231 capture, to a file.  Check boxes let you select whether to save all
232 packets, or just those that have passed the current display filter and/or
233 those that are currently marked, and an option menu lets you select (from 
234 a list of file formats in which at particular capture, or the packets 
235 currently displayed from that capture, can be saved), a file format in 
236 which to save it.
237
238 =item File:Print
239
240 Prints, for all the packets in the current capture, either the summary
241 line for the packet or the protocol tree view of the packet; when
242 printing the protocol tree view, the hex dump of the packet can be
243 printed as well.  Printing options can be set with the
244 I<Edit:Preferences> menu item, or in the dialog box popped up by this
245 item.
246
247 =item File:Print Packet
248
249 Print a fully-expanded protocol tree view of the currently-selected
250 packet.  Printing options can be set with the I<Edit:Preferences> menu
251 item.
252
253 =item File:Quit
254
255 Exits the application.
256
257 =item Edit:Find Frame
258
259 Allows you to search forward or backward, starting with the currently
260 selected packet (or the most recently selected packet, if no packet is
261 selected), for a packet matching a given display filter.
262
263 =item Edit:Go To Frame
264
265 Allows you to go to a particular numbered packet.
266
267 =item Edit:Mark Frame
268
269 Allows you to mark (or unmark if currently marked) the selected packet.
270
271 =item Edit:Mark All Frames
272
273 Allows you to mark all packets that are currently displayed.
274
275 =item Edit:Unmark All Frames
276
277 Allows you to unmark all packets that are currently displayed.
278
279 =item Edit:Preferences
280
281 Sets the packet printing, column display, TCP stream coloring, and GUI
282 options (see L<"Preferences"> below).
283
284 =item Edit:Capture Filters
285
286 Edits the saved list of capture filters, allowing filters to be added,
287 changed, or deleted.
288
289 =item Edit:Display Filters
290
291 Edits the saved list of display filters, allowing filters to be added,
292 changed, or deleted.
293
294 =item Edit:Protocols
295
296 Edits the list of protocols, allowing protocol dissection to be 
297 enabled or disabled.
298
299 =item Capture:Start
300
301 Initiates a live packet capture (see L<"Capture Preferences"> below).  A
302 temporary file will be created to hold the capture.  The location of the
303 file can be chosen by setting your TMPDIR environment variable before
304 starting B<Ethereal>.  Otherwise, the default TMPDIR location is
305 system-dependent, but is likely either F</var/tmp> or F</tmp>.
306
307 =item Capture:Stop
308
309 In a capture that updates the packet display as packets arrive (so that
310 Ethereal responds to user input other than pressing the "Stop" button in
311 the capture packet statistics dialog box), stops the capture.
312
313 =item Display:Options
314
315 Allows you to sets the format of the packet timestamp displayed in the
316 packet list window to relative, absolute, absolute date and time, or
317 delta, to enable or disable the automatic scrolling of the packet list
318 while a live capture is in progress or to enable or disable translation
319 of addresses to names in the display.
320
321 =item Display:Match Selected
322
323 Creates and applies a display filter based on the data that is currently
324 highlighted in the protocol tree.  If that data is a field that can be
325 tested in a display filter expression, the display filter will test that
326 field; otherwise, the display filter will be based on absolute offset
327 within the packet, and so could be unreliable if the packet contains
328 protocols with variable-length headers, such as a source-routed
329 token-ring packet.
330
331 =item Display:Colorize Display
332
333 Allows you to change the foreground and background colors of the packet
334 information in the list of packets, based upon display filters.  The list
335 of display filters is applied to each packet sequentially. After the first
336 display filter matches a packet, any additional display filters in the list
337 are ignored. Therefore, if you are filtering on the existence of protocols,
338 you should list the higher-level protocols first, and the lower-level
339 protocols last.
340
341 =item Display:Collapse All
342
343 Collapses the protocol tree branches.
344
345 =item Display:Expand All
346
347 Expands all branches of the protocol tree.
348
349 =item Display:Expand All
350
351 Expands all branches of the protocol tree.
352
353 =item Display:Show Packet In New Window
354
355 Creates a new window containing a protocol tree view and a hex dump
356 window of the currently selected packet; this window will continue to
357 display that packet's protocol tree and data even if another packet is
358 selected.
359
360 =item Display:User Specified Decodes
361
362 Creates a new window showing whether any protocol ID to dissector
363 mappings have been changed by the user.  This window also allows the
364 user to reset all decodes to their default values.
365
366 =item Tools:Plugins
367
368 Allows you to see what dynamically loadable dissector plugin modules
369 have been loaded (see I<"Plugins"> below).
370
371 =item Tools:Follow TCP Stream
372
373 If you have a TCP packet selected, it will display the contents of the
374 data stream for the TCP connection to which that packet belongs, as
375 text, in a separate window, and will leave the list of packets in a
376 filtered state, with only those packets that are part of that TCP
377 connection being displayed.  You can revert to your old view by pressing
378 ENTER in the display filter text box, thereby invoking your old display
379 filter (or resetting it back to no display filter).
380
381 The window in which the data stream is displayed lets you select whether
382 to display:
383
384 =over 4
385
386 =item
387
388 whether to display the entire conversation, or one or the other side of
389 it;
390
391 =item
392
393 whether the data being displayed is to be treated as ASCII or EBCDIC
394 text or as raw hex data;
395
396 =back
397
398 =back
399
400 =over 4
401
402 =item
403
404 and lets you print what's currently being displayed, using the same
405 print options that are used for the I<File:Print Packet> menu item, or
406 save it as text to a file.
407
408 =back
409
410 =item Tools:Decode As
411
412 If you have a packet selected, this menu item will present a dialog
413 allowing you to change which dissectors are used to decode this
414 packet.  The dialog has one panel each for the link layer, network
415 layer and transport layer protocol/port numbers, and will allow each
416 of these to be changed independently.  For example, if the selected
417 packet is a TCP packet to port 12345, using this dialog you can
418 instruct Ethereal to decode all packets to or from that TCP port as
419 HTTP packets.
420
421 =item Tools:Protocol Hierarchy Statistics
422
423 This shows the number of packets, and the number of bytes
424 in those packets, for each protocol in the trace. It
425 organizes the protocols in the same hierarchy in which
426 they were found in the trace. Besides counting the packets
427 in which the protocol exists, a count is also made
428 for packets in which the protocol is the last protocol in
429 the stack. These last-protocol counts show you how many packets
430 (and the byte count associated with those packets) B<ended> in a particular
431 protocol. In the table, they are listed under "End Packets" and
432 "End Bytes".
433
434 =head2 WINDOWS
435
436 =over 4
437
438 =item Main Window
439
440 The main window is split into three panes.  You can resize each pane using
441 a "thumb" at the right end of each divider line.  Below the panes is a
442 strip that shows the current filter and informational text.
443
444 =over 6
445
446 =item Top Pane
447
448 The top pane contains the list of network packets that you can scroll
449 through and select.  By default, the packet number, packet timestamp,
450 source and destination addresses, protocol, and description are
451 displayed for each packet; the I<Columns> page in the dialog box popped
452 up by I<Edit:Preferences> lets you change this (although, unfortunately,
453 you currently have to save the preferences, and exit and restart
454 Ethereal, for those changes to take effect).
455
456 If you click on the heading for a column, the display will be sorted by
457 that column; clicking on the heading again will reverse the sort order
458 for that column.
459
460 An effort is made to display information as high up the protocol stack
461 as possible, e.g. IP addresses are displayed for IP packets, but the
462 MAC layer address is displayed for unknown packet types.
463
464 The right mouse button can be used to pop up a menu of operations.
465
466 The middle mouse button can be used to mark a packet.
467
468 =item Middle Pane
469
470 The middle pane contains a I<protocol tree> for the currently-selected
471 packet.  The tree displays each field and its value in each protocol
472 header in the stack.  The right mouse button can be used to pop up a
473 menu of operations.
474
475 =item Bottom Pane
476
477 The lowest pane contains a hex dump of the actual packet data. 
478 Selecting a field in the I<protocol tree> highlights the corresponding
479 bytes in this section.
480
481 The right mouse button can be used to pop up a menu of operations.
482
483 =item Current Filter
484
485 A display filter can be entered into the strip at the bottom. 
486 A filter for HTTP, HTTPS, and DNS traffic might look like this:
487
488   tcp.port == 80 || tcp.port == 443 || tcp.port == 53
489
490 Selecting the I<Filter:> button lets you choose from a list of named
491 filters that you can optionally save.  Pressing the Return or Enter
492 keys will cause the filter to be applied to the current list of packets.
493 Selecting the I<Reset> button clears the display filter so that all
494 packets are displayed.
495
496 =back
497
498 =item Preferences
499
500 The I<Preferences> dialog lets you control various personal preferences
501 for the behavior of B<Ethereal>.
502
503 =over 6
504
505 =item Printing Preferences
506
507 The radio buttons at the top of the I<Printing> page allow you choose
508 between printing packets with the I<File:Print Packet> menu item as text
509 or PostScript, and sending the output directly to a command or saving it
510 to a file.  The I<Command:> text entry box is the command to send files
511 to (usually B<lpr>), and the I<File:> entry box lets you enter the name
512 of the file you wish to save to.  Additionally, you can select the
513 I<File:> button to browse the file system for a particular save file.
514
515 =item Column Preferences
516
517 The I<Columns> page lets you specify the number, title, and format
518 of each column in the packet list.
519
520 The I<Column title> entry is used to specify the title of the column
521 displayed at the top of the packet list.  The type of data that the column
522 displays can be specified using the I<Column format> option menu.
523 The row of buttons on the left perform the following actions:
524
525 =over 6
526
527 =item New
528
529 Adds a new column to the list.
530
531 =item Change
532
533 Modifies the currently selected list item.
534
535 =item Delete
536
537 Deletes the currently selected list item.
538
539 =item Up / Down
540
541 Moves the selected list item up or down one position.
542
543 =item OK
544
545 Currently has no effect.
546
547 =item Save
548
549 Saves the current column format as the default.
550
551 =item Cancel
552
553 Closes the dialog without making any changes.
554
555 =back
556
557 =item TCP Stream Preferences
558
559 The I<TCP Streams> page can be used to change the color of the text
560 displayed in the TCP stream window.  To change a color, simply select
561 an attribute from the "Set:" menu and use the color selector to get the
562 desired color.  The new text colors are displayed in a sample window.
563
564 =item GUI Preferences
565
566 The I<GUI> page is used to modify small aspects of the GUI to your own
567 personal taste:
568
569 =over 6
570
571 =item Scrollbars
572
573 The vertical scrollbars in the three panes can be set to be either on
574 the left or the right. 
575
576 =item Selection Bars
577
578 The selection bar in the
579 packet list and protocol tree can have either a "browse" or "select"
580 behavior. If the selection bar has a "browse" behavior, the arrow keys
581 will move an outline of the selection bar, allowing you to browse
582 the rest of the list or tree without changing the selection
583 until you press the space bar. If the selection bar has a "select"
584 behavior, the arrow keys will move the selection bar and change
585 the selection to the new item in the packet list or protocol tree.
586 The highlight method in the hex dump display for the selected protocol
587 item can be set to use either inverse video, or bold characters.
588
589 =item Fonts
590
591 The "Font..." button lets you select the font to be used for most text.
592
593 =item Colors
594
595 The "Colors..." button lets you select the colors to be used for instance
596 for the marked frames.
597
598 =back
599
600 =item Protocol Preferences
601
602 There are also pages for various protocols that Ethereal dissects,
603 controlling the way Ethereal handles those protocols.
604
605 =back
606
607 =item Edit Capture Filter List
608
609 =item Edit Display Filter List
610
611 =item Capture Filter
612
613 =item Display Filter
614
615 =item Read Filter
616
617 =item Search Filter
618
619 The I<Edit Capture Filter List> dialog lets you create, modify, and
620 delete capture filters, and the I<Edit Display Filter List> dialog lets
621 you create, modify, and delete display filters.
622
623 The I<Capture Filter> dialog lets you do all of the editing operations
624 listed, and also lets you choose or construct a filter to be used when
625 capturing packets.
626
627 The I<Display Filter> dialog lets you do all of the editing operations
628 listed, and also lets you choose or construct a filter to be used to
629 filter the current capture being viewed.
630
631 The I<Read Filter> dialog lets you do all of the editing operations
632 listed, and also lets you choose or construct a filter to be used to
633 as a read filter for a capture file you open.
634
635 The I<Search Filter> dialog lets you do all of the editing operations
636 listed, and also lets you choose or construct a filter expression to be
637 used in a find operation.
638
639 In all of those dialogs, the I<Filter name> entry specifies a
640 descriptive name for a filter, e.g.  B<Web and DNS traffic>.  The
641 I<Filter string> entry is the text that actually describes the filtering
642 action to take, as described above.The dialog buttons perform the
643 following actions:
644
645 =over 6
646
647 =item New
648
649 If there is text in the two entry boxes, creates a new associated list
650 item.
651
652 =item Change
653
654 Modifies the currently selected list item to match what's in the entry
655 boxes.
656
657 =item Copy
658
659 Makes a copy of the currently selected list item.
660
661 =item Delete
662
663 Deletes the currently selected list item.
664
665 =item Add Expression...
666
667 For display filter expressions, pops up a dialog box to allow you to
668 construct a filter expression to test a particular field; it offers
669 lists of field names, and, when appropriate, lists from which to select
670 tests to perform on the field and values with which to compare it.  In
671 that dialog box, the OK button will cause the filter expression you
672 constructed to be entered into the I<Filter string> entry at the current
673 cursor position.
674
675 =item OK
676
677 In the I<Capture Filter> dialog, closes the dialog box and makes the
678 filter in the I<Filter string> entry the filter in the I<Capture
679 Preferences> dialog.  In the I<Display Filter> dialog, closes the dialog
680 box and makes the filter in the I<Filter string> entry the current
681 display filter, and applies it to the current capture.  In the I<Read
682 Filter> dialog, closes the dialog box and makes the filter in the
683 I<Filter string> entry the filter in the I<Open Capture File> dialog. 
684 In the I<Search Filter> dialog, closes the dialog box and makes the
685 filter in the I<Filter string> entry the filter in the I<Find Frame>
686 dialog.
687
688 =item Apply
689
690 Makes the filter in the I<Filter string> entry the current display
691 filter, and applies it to the current capture.
692
693 =item Save
694
695 Saves the current filter list in F<$HOME/.ethereal/cfilters> on
696 UNIX-compatible systems, and F<%USERPROFILE%\.ethereal\cfilters> on
697 Windows systems, if the list of filters being edited is the list of
698 capture filters, or in F<$HOME/.ethereal/dfilters> on UNIX-compatible
699 systems, and F<%USERPROFILE%\.ethereal\dfilters> on Windows systems, if
700 the list of filters being edited is the list of display filters.
701
702 =item Close
703
704 Closes the dialog without doing anything with the filter in the I<Filter
705 string> entry.
706
707 =back
708
709 =item Capture Preferences
710
711 The I<Capture Preferences> dialog lets you specify various parameters for
712 capturing live packet data.
713
714 The I<Interface:> combo box lets you specify the interface from which to
715 capture packet data, or the name of a FIFO from which to get the packet
716 data.  The I<Count:> entry specifies the number of packets to capture. 
717 Entering 0 will capture packets indefinitely.  The I<Filter:> entry lets
718 you specify the capture filter using a tcpdump-style filter string as
719 described above.  The I<File:> entry specifies the file to save to, as
720 in the I<Printer Options> dialog above.  You can specify the maximum
721 number of bytes to capture per packet with the I<Capture length> entry,
722 can specify whether the interface is to be put in promiscuous mode or
723 not with the I<Capture packets in promiscuous mode> check box, can
724 specify that the display should be updated as packets are captured with
725 the I<Update list of packets in real time> check box, can specify
726 whether in such a capture the packet list pane should scroll to show the
727 most recently captured packets with the I<Automatic scrolling in live
728 capture> check box, and can specify whether addresses should be
729 translated to names in the display with the I<Enable MAC name resolution>,
730 I<Enable network name resolution> and I<Enable transport name resolution>
731 check boxes.
732
733 =item Display Options
734
735 The I<Display Options> dialog lets you specify the format of the time
736 stamp in the packet list.  You can select "Time of day" for absolute
737 time stamps, "Date and time of day" for absolute time stamps with the
738 date, "Seconds since beginning of capture" for relative time stamps, or
739 "Seconds since previous frame" for delta time stamps.  You can also
740 specify whether, when the display is updated as packets are captured,
741 the list should automatically scroll to show the most recently captured
742 packets or not and whether addresses or port numbers should be
743 translated to names in the display on a MAC, network and transport layer
744 basis.
745
746 =item Plugins
747
748 The I<Plugins> dialog lets you view the dissector plugin modules
749 available on your system.
750
751 The I<Plugins List> shows the name and version of each dissector plugin
752 module found on your system.  The plugins are searched in the following
753 directories: the F<lib/ethereal/plugins/$VERSION> directory under the
754 main installation directory (for example,
755 F</usr/local/lib/ethereal/plugins/$VERSION>),
756 F</usr/lib/ethereal/plugins/$VERSION>,
757 F</usr/local/lib/ethereal/plugins/$VERSION>, and
758 F<$HOME/.ethereal/plugins> on UNIX-compatible systems, and in the
759 F<plugins\$VERSION> directory under the main installation directory (for
760 example, F<C:\Program Files\Ethereal\plugins\$VERSION>) and
761 F<%USERPROFILE%\.ethereal\plugins\$VERSION> on Windows
762 systems; $VERSION is the version number of the plugin interface, which
763 is typically the version number of Ethereal.  Note that a dissector
764 plugin module may support more than one protocol; there is not
765 necessarily a one-to-one correspondence between dissector plugin modules
766 and protocols.  Protocols supported by a dissector plugin module are
767 enabled and disabled using the I<Edit:Protocols> dialog box, just as
768 protocols built into Ethereal are.
769
770 =head1 CAPTURE FILTER SYNTAX
771
772 See manual page of tcpdump(8).
773
774 =head1 DISPLAY FILTER SYNTAX
775
776 Display filters help you remove the noise from a packet trace and let
777 you see only the packets that interest you.  If a packet meets the
778 requirements expressed in your display filter, then it is displayed in
779 the list of packets.  Display filters let you compare the fields within
780 a protocol against a specific value, compare fields against fields, and
781 to check the existence of specified fields or protocols.
782
783 The simplest display filter allows you to check for the existence of a
784 protocol or field.  If you want to see all packets which contain the IPX
785 protocol, the filter would be "ipx".  (Without the quotation marks) To
786 see all packets that contain a Token-Ring RIF field, use "tr.rif".
787
788 Fields can also be compared against values.  The comparison operators
789 can be expressed either through C-like symbols, or through English-like
790 abbreviations:
791
792     eq, ==    Equal
793     ne, !=    Not equal
794     gt, >     Greater than
795     lt, <     Less Than
796     ge, >=    Greater than or Equal to
797     le, <=    Less than or Equal to
798
799 Furthermore, each protocol field is typed. The types are:
800
801     Unsigned integer (either 8-bit, 16-bit, 24-bit, or 32-bit)
802     Signed integer (either 8-bit, 16-bit, 24-bit, or 32-bit)
803     Boolean
804     Ethernet address (6 bytes)
805     Byte string (n-number of bytes)
806     IPv4 address
807     IPv6 address
808     IPX network number
809     String (text)
810     Double-precision floating point number
811
812 An integer may be expressed in decimal, octal, or hexadecimal notation. 
813 The following three display filters are equivalent:
814
815     frame.pkt_len > 10
816     frame.pkt_len > 012
817     frame.pkt_len > 0xa
818
819 Boolean values are either true or false.  In a display filter expression
820 testing the value of a Boolean field, "true" is expressed as 1 or any
821 other non-zero value, and "false" is expressed as zero.  For example, a
822 token-ring packet's source route field is boolean.  To find any
823 source-routed packets, a display filter would be:
824
825     tr.sr == 1
826
827 Non source-routed packets can be found with:
828
829     tr.sr == 0
830
831 Ethernet addresses, as well as a string of bytes, are represented in hex
832 digits.  The hex digits may be separated by colons, periods, or hyphens:
833
834     fddi.dst eq ff:ff:ff:ff:ff:ff
835     ipx.srcnode == 0.0.0.0.0.1
836     eth.src == aa-aa-aa-aa-aa-aa
837
838 If a string of bytes contains only one byte, then it is represented as
839 an unsigned integer.  That is, if you are testing for hex value 'ff' in
840 a one-byte byte-string, you must compare it agains '0xff' and not 'ff'. 
841
842 IPv4 addresses can be represented in either dotted decimal notation, or
843 by using the hostname:
844
845     ip.dst eq www.mit.edu
846     ip.src == 192.168.1.1
847
848 IPv4 addresses can be compared with the same logical relations as numbers:
849 eq, ne, gt, ge, lt, and le.  The IPv4 address is stored in host order,
850 so you do not have to worry about how the endianness of an IPv4 address
851 when using it in a display filter.
852
853 Classless InterDomain Routing (CIDR) notation can be used to test if an
854 IPv4 address is in a certain subnet.  For example, this display filter
855 will find all packets in the 129.111 Class-B network:
856
857     ip.addr == 129.111.0.0/16
858
859 Remember, the number after the slash represents the number of bits used
860 to represent the network.  CIDR notation can also be used with
861 hostnames, in this example of finding IP addresses on the same Class C
862 network as 'sneezy':
863
864     ip.addr eq sneezy/24
865
866 The CIDR notation can only be used on IP addresses or hostnames, not in
867 variable names.  So, a display filter like "ip.src/24 == ip.dst/24" is
868 not valid.  (yet)
869
870 IPX networks are represented by unsigned 32-bit integers.  Most likely
871 you will be using hexadecimal when testing for IPX network values:
872
873     ipx.srcnet == 0xc0a82c00
874
875 A slice operator also exists.  You can check the substring
876 (byte-string) of any protocol or field.  For example, you can filter on
877 the vendor portion of an ethernet address (the first three bytes) like
878 this:
879
880     eth.src[0:3] == 00:00:83
881
882 If the length of your byte-slice is only one byte, then it is still
883 represented in hex, but without the preceding "0x": 
884
885     llc[3] == aa
886
887 You can use the slice operator on a protocol name, too.  And
888 remember, the "frame" protocol encompasses the entire packet, allowing
889 you to look at the nth byte of a packet regardless of its frame type
890 (Ethernet, token-ring, etc.).
891
892     token[0:5] ne 0.0.0.1.1
893     ipx[0:2] == ff:ff
894     llc[3:1] eq 0xaa
895
896 The following syntax governs slices:
897
898         [i:j]   i = start_offset, j = length
899         [i-j]   i = start_offet, j = end_offset, inclusive.
900         [i]     i = start_offset, length = 1
901         [:j]    start_offset = 0, length = j
902         [i:]    start_offset = i, end_offset = end_of_field
903
904 Offsets and lengths can be negative, in which case they indicate the
905 offset from the B<end> of the field.  Here's how to check the last 4
906 bytes of a frame:
907
908     frame[-4:4] == 0.1.2.3
909
910 or
911
912     frame[-4:] == 0.1.2.3
913
914 You can create complex concatenations of slices using the comma operator:
915
916         field[1,3-5,9:] == 01:03:04:05:09:0a:0b
917
918 All the above tests can be combined together with logical expressions. 
919 These too are expressable in C-like syntax or with English-like
920 abbreviations:
921
922     and, &&   Logical AND
923     or, ||    Logical OR
924     not, !    Logical NOT
925
926 Expressions can be grouped by parentheses as well.  The following are
927 all valid display filter expression:
928
929     tcp.port == 80 and ip.src == 192.168.2.1
930     not llc
931     (ipx.srcnet == 0xbad && ipx.srnode == 0.0.0.0.0.1) || ip
932     tr.dst[0:3] == 0.6.29 xor tr.src[0:3] == 0.6.29
933
934 A special caveat must be given regarding fields that occur more than
935 once per packet.  "ip.addr" occurs twice per IP packet, once for the
936 source address, and once for the destination address.  Likewise,
937 tr.rif.ring fields can occur more than once per packet.  The following
938 two expressions are not equivalent:
939
940         ip.addr ne 192.168.4.1
941     not ip.addr eq 192.168.4.1
942
943 The first filter says "show me all packets where an ip.addr exists that
944 does not equal 192.168.4.1".  That is, as long as one ip.addr in the
945 packet does not equal 192.168.44.1, the packet passes the display
946 filter.  The second filter "don't show me any packets that have at least
947 one ip.addr field equal to 192.168.4.1".  If one ip.addr is 192.168.4.1,
948 the packet does not pass.  If B<neither> ip.addr fields is 192.168.4.1,
949 then the packet passes.
950
951 It is easy to think of the 'ne' and 'eq' operators as having an implict
952 "exists" modifier when dealing with multiply-recurring fields.  "ip.addr
953 ne 192.168.4.1" can be thought of as "there exists an ip.addr that does
954 not equal 192.168.4.1".
955
956 Be careful with multiply-recurring fields; they can be confusing.
957
958 The following is a table of protocol and protocol fields that are
959 filterable in B<Ethereal>.  The abbreviation of the protocol or field is
960 given.  This abbreviation is what you use in the display filter.  The
961 type of the field is also given.
962
963 =insert_dfilter_table
964
965 =head1 FILES
966
967 The F<ethereal.conf> file, which is installed in the F<etc> directory
968 under the main installation directory (for example, F</usr/local/etc>)
969 on UNIX-compatible systems, and in the main installation directory (for
970 example, F<C:\Program Files\Ethereal>) on Windows systems, and the
971 personal preferences file, which is F<$HOME/.ethereal/preferences> on
972 UNIX-compatible systems and F<%USERPROFILE%\.ethereal\preferences> on
973 Windows systems, contain system-wide and personal preference settings,
974 respectively.  The file contains preference settings of the form
975 I<prefname>B<:>I<value>, one per line, where I<prefname> is the name of
976 the preference (which is the same name that would appear in the
977 preference file), and I<value> is the value to which it should be set;
978 white space is allowed between B<:> and I<value>.  A preference setting
979 can be continued on subsequent lines by indenting the continuation lines
980 with white space.  A B<#> character starts a comment that runs to the
981 end of the line.
982
983 The system-wide preference file is read first, if it exists, overriding
984 B<Ethereal>'s default values; the personal preferences file is then
985 read, if it exists, overriding default values and values read from the
986 system-wide preference file.
987
988 Note that whenever the preferences are saved by using the I<Save> button
989 in the I<Edit:Preferences> dialog box, your personal preferences file
990 will be overwritten with the new settings, destroying any comments that
991 were in the file.
992
993 The F<ethers> file, which is found in the F</etc> directory on
994 UNIX-compatible systems, and in the main installation directory (for
995 example, F<C:\Program Files\Ethereal>) on Windows systems, is consulted
996 to correlate 6-byte hardware addresses to names.  If an address is not
997 found in the F<ethers> file, the F<$HOME/.ethereal/ethers> file on
998 UNIX-compatible systems, and the F<%USERPROFILE%\.ethereal\ethers> file
999 on Windows systems is consulted next.  Each line contains one hardware
1000 address and name, separated by whitespace.  The digits of the hardware
1001 address are separated by either a colon (:), a dash (-), or a period
1002 (.).  The following three lines are valid lines of an ethers file:
1003
1004   ff:ff:ff:ff:ff:ff          Broadcast
1005   c0-00-ff-ff-ff-ff          TR_broadcast
1006   00.00.00.00.00.00          Zero_broadcast
1007
1008 The F<manuf> file, which is installed in the F<etc> directory under the
1009 main installation directory (for example, F</usr/local/etc>) on
1010 UNIX-compatible systems, and in the main installation directory (for
1011 example, F<C:\Program Files\Ethereal>) on Windows systems, matches the
1012 3-byte vendor portion of a 6-byte hardware address with the
1013 manufacturer's name.  The format of the file is the same as the
1014 F<ethers> file, except that each address is three bytes instead of six.
1015
1016 The F<ipxnets> file, which is found in the F</etc> directory on
1017 UNIX-compatible systems, and in the main installation directory (for
1018 example, F<C:\Program Files\Ethereal>) on Windows systems, correlates
1019 4-byte IPX network numbers to names.  If a network number is not found
1020 in the F<ipxnets> file, the F<$HOME/.ethereal/ipxnets> file on
1021 UNIX-compatible systems, and the F<%USERPROFILE%\.ethereal\ipxnets> file
1022 on Windows systems, is consulted next.  The format is the same as the
1023 F<ethers> file, except that each address if four bytes instead of six. 
1024 Additionally, the address can be represented a single hexadecimal
1025 number, as is more common in the IPX world, rather than four hex octets. 
1026 For example, these four lines are valid lines of an ipxnets file.
1027
1028   C0.A8.2C.00              HR
1029   c0-a8-1c-00              CEO
1030   00:00:BE:EF              IT_Server1
1031   110f                     FileServer3
1032
1033 =head1 SEE ALSO
1034
1035 L<tethereal(1)>, L<editcap(1)>, L<tcpdump(8)>, L<pcap(3)>
1036
1037 =head1 NOTES
1038
1039 The latest version of B<Ethereal> can be found at
1040 B<http://www.ethereal.com>.
1041
1042 =head1 AUTHORS
1043
1044   Original Author
1045   -------- ------
1046   Gerald Combs  <gerald[AT]ethereal.com>
1047
1048
1049   Contributors
1050   ------------
1051   Gilbert Ramirez          <gram[AT]xiexie.org>
1052   Hannes R. Boehm          <hannes[AT]boehm.org>
1053   Mike Hall                <mlh[AT]io.com>
1054   Bobo Rajec               <bobo[AT]bsp-consulting.sk>
1055   Laurent Deniel           <deniel[AT]worldnet.fr>
1056   Don Lafontaine           <lafont02[AT]cn.ca>
1057   Guy Harris               <guy[AT]alum.mit.edu>
1058   Simon Wilkinson          <sxw[AT]dcs.ed.ac.uk>
1059   Joerg Mayer              <jmayer[AT]loplof.de>
1060   Martin Maciaszek         <fastjack[AT]i-s-o.net>
1061   Didier Jorand            <Didier.Jorand[AT]alcatel.fr>
1062   Jun-ichiro itojun Hagino <itojun[AT]iijlab.net>
1063   Richard Sharpe           <sharpe[AT]ns.aus.com>
1064   John McDermott           <jjm[AT]jkintl.com> 
1065   Jeff Jahr                <jjahr[AT]shastanets.com>
1066   Brad Robel-Forrest       <bradr[AT]watchguard.com>
1067   Ashok Narayanan          <ashokn[AT]cisco.com>
1068   Aaron Hillegass          <aaron[AT]classmax.com>
1069   Jason Lango              <jal[AT]netapp.com>
1070   Johan Feyaerts           <Johan.Feyaerts[AT]siemens.atea.be>
1071   Olivier Abad             <oabad[AT]cybercable.fr>
1072   Thierry Andry            <Thierry.Andry[AT]advalvas.be>
1073   Jeff Foster              <jjfoste[AT]woodward.com>
1074   Peter Torvals            <petertv[AT]xoommail.com>
1075   Christophe Tronche       <ch.tronche[AT]computer.org>
1076   Nathan Neulinger         <nneul[AT]umr.edu>
1077   Tomislav Vujec           <tvujec[AT]carnet.hr>
1078   Kojak                    <kojak[AT]bigwig.net>
1079   Uwe Girlich              <Uwe.Girlich[AT]philosys.de>
1080   Warren Young             <tangent[AT]mail.com>
1081   Heikki Vatiainen         <hessu[AT]cs.tut.fi>
1082   Greg Hankins             <gregh[AT]twoguys.org>
1083   Jerry Talkington         <jerryt[AT]netapp.com>
1084   Dave Chapeskie           <dchapes[AT]ddm.on.ca>
1085   James Coe                <jammer[AT]cin.net>
1086   Bert Driehuis            <driehuis[AT]playbeing.org>
1087   Stuart Stanley           <stuarts[AT]mxmail.net>
1088   John Thomes              <john[AT]ensemblecom.com>
1089   Laurent Cazalet          <laurent.cazalet[AT]mailclub.net>
1090   Thomas Parvais           <thomas.parvais[AT]advalvas.be>
1091   Gerrit Gehnen            <G.Gehnen[AT]atrie.de>
1092   Craig Newell             <craign[AT]cheque.uq.edu.au>
1093   Ed Meaney                <emeaney[AT]altiga.com>
1094   Dietmar Petras           <DPetras[AT]ELSA.de> 
1095   Fred Reimer              <fwr[AT]ga.prestige.net>
1096   Florian Lohoff           <flo[AT]rfc822.org>
1097   Jochen Friedrich         <jochen+ethereal[AT]scram.de>
1098   Paul Welchinski          <paul.welchinski[AT]telusplanet.net>
1099   Doug Nazar               <nazard[AT]dragoninc.on.ca>
1100   Andreas Sikkema          <andreas.sikkema[AT]philips.com>
1101   Mark Muhlestein          <mmm[AT]netapp.com>
1102   Graham Bloice            <graham.bloice[AT]trihedral.com>
1103   Ralf Schneider           <ralf.schneider[AT]alcatel.se>
1104   Yaniv Kaul               <ykaul[AT]netvision.net.il>
1105   Paul Ionescu             <ipaul[AT]romsys.ro>
1106   Mark Burton              <markb[AT]ordern.com>
1107   Stefan Raab              <sraab[AT]cisco.com>
1108   Mark Clayton             <clayton[AT]shore.net>
1109   Michael Rozhavsky        <mike[AT]tochna.technion.ac.il>
1110   Dug Song                 <dugsong[AT]monkey.org>
1111   Michael Tuexen           <Michael.Tuexen[AT]icn.siemens.de>
1112   Bruce Korb               <bkorb[AT]sco.com>
1113   Jose Pedro Oliveira      <jpo[AT]di.uminho.pt>
1114   David Frascone           <dave[AT]frascone.com>
1115   Peter Kjellerstedt       <pkj[AT]axis.com>
1116   Phil Techau              <phil_t[AT]altavista.net>
1117   Wes Hardaker             <wjhardaker[AT]ucdavis.edu>
1118   Robert Tsai              <rtsai[AT]netapp.com>
1119   Craig Metz               <cmetz[AT]inner.net>
1120   Per Flock                <per.flock[AT]axis.com>
1121   Jack Keane               <jkeane[AT]OpenReach.com>
1122   Brian Wellington         <bwelling[AT]xbill.org>
1123   Santeri Paavolainen      <santtu[AT]ssh.com>
1124   Ulrich Kiermayr          <uk[AT]ap.univie.ac.at>
1125   Neil Hunter              <neil.hunter[AT]energis-squared.com>
1126   Ralf Holzer              <ralf[AT]well.com>
1127   Craig Rodrigues          <rodrigc[AT]mediaone.net>
1128   Ed Warnicke              <hagbard[AT]physics.rutgers.edu>
1129   Johan Jorgensen          <johan.jorgensen[AT]axis.com>
1130   Frank Singleton          <frank.singleton[AT]ericsson.com>
1131   Kevin Shi                <techishi[AT]ms22.hinet.net>
1132   Mike Frisch              <mfrisch[AT]saturn.tlug.org>
1133   Burke Lau                <burke_lau[AT]agilent.com>
1134   Martti Kuparinen         <martti.kuparinen[AT]iki.fi>
1135   David Hampton            <dhampton[AT]mac.com>
1136   Kent Engström            <kent[AT]unit.liu.se>
1137   Ronnie Sahlberg          <rsahlber[AT]bigpond.net.au>
1138   Alexandre P. Ferreira    <alexandref[AT]spliceip.com.br>
1139   Simharajan Srishylam     <Simharajan.Srishylam[AT]netapp.com>
1140   Greg Kilfoyle            <gregk[AT]redback.com>
1141   James E. Flemer          <jflemer[AT]acm.jhu.edu>
1142   Peter Lei                <peterlei[AT]cisco.com>
1143   Thomas Gimpel            <thomas.gimpel[AT]ferrari.de>
1144   Albert Chin              <china[AT]thewrittenword.com>
1145   Charles Levert           <charles[AT]comm.polymtl.ca>
1146   Todd Sabin               <tas[AT]webspan.net>
1147   Eduardo Pérez Ureta      <eperez[AT]dei.inf.uc3m.es>
1148   Martin Thomas            <martin_a_thomas[AT]yahoo.com>
1149   Hartmut Mueller          <hartmut[AT]wendolene.ping.de>
1150   Michal Melerowicz        <Michal.Melerowicz[AT]nokia.com>
1151   Hannes Gredler           <hannes[AT]juniper.net>
1152   Inoue                    <inoue[AT]ainet.or.jp>
1153   Olivier Biot             <Olivier.Biot[AT]siemens.atea.be>
1154   Patrick Wolfe            <pjw[AT]zocalo.cellular.ameritech.com>
1155   Martin Held              <Martin.Held[AT]icn.siemens.de>
1156   Riaan Swart              <rswart[AT]cs.sun.ac.za>
1157   Christian Lacunza        <celacunza[AT]gmx.net>
1158   Michael Rozhavsky        <mike[AT]tochna.technion.ac.il>
1159   Scott Renfro             <scott[AT]renfro.org>
1160   Juan Toledo              <toledo[AT]users.sourceforge.net>
1161   Jean-Christian Pennetier <jeanchristian.pennetier[AT]rd.francetelecom.fr>
1162   Jian Yu                  <bgp4news[AT]yahoo.com>
1163   Eran Mann                <emann[AT]opticalaccess.com>
1164   Andy Hood                <ahood[AT]westpac.com.au>
1165   Randy McEoin             <rmceoin[AT]pe.net>
1166   Edgar Iglesias           <edgar.iglesias[AT]axis.com>
1167   Martina Obermeier        <Martina.Obermeier[AT]icn.siemens.de>
1168   Mark Burton              <markb[AT]ordern.com>
1169   Javier Achirica          <achirica[AT]ttd.net>
1170   B. Johannessen           <bob[AT]havoq.com>
1171   Thierry Pelle            <thierry.pelle[AT]rd.francetelecom.fr>
1172   Francisco Javier Cabello <fjcabello[AT]vtools.es>
1173   Laurent Rabret           <laurent.rabret[AT]rd.francetelecom.fr>
1174   nuf si                   <gnippiks[AT]yahoo.com>
1175   Jeff Morriss             <jeff.morriss[AT]ulticom.com>
1176   Aamer Akhter             <aakhter[AT]cisco.com>
1177   Pekka Savola             <pekkas[AT]netcore.fi>
1178   David Eisner             <cradle[AT]Glue.umd.edu>
1179   Steve Dickson            <steved[AT]talarian.com>
1180   Markus Seehofer          <mseehofe[AT]nt.hirschmann.de>
1181   Lee Berger               <lberger[AT]roy.org>
1182   Motonori Shindo          <mshindo[AT]mshindo.net>
1183   Terje Krogdahl           <tekr[AT]nextra.com>
1184   Jean-Francois Mule       <jfmule[AT]clarent.com>
1185   Thomas Wittwer           <thomas.wittwer[AT]iclip.ch>
1186   Palle Lyckegaard         <Palle[AT]lyckegaard.dk>
1187   Nicolas Balkota          <balkota[AT]mac.com>
1188   Tom Uijldert             <Tom.Uijldert[AT]cmg.nl>
1189   Endoh Akira              <endoh[AT]netmarks.co.jp>
1190   Graeme Hewson            <graeme.hewson[AT]oracle.com>
1191   Pasi Eronen              <pasi.eronen[at]nixu.com>
1192   Georg von Zezschwitz     <gvz[AT]2scale.net>
1193   Steffen Weinreich        <steve[AT]weinreich.org>
1194   Marc Milgram             <mmilgram[AT]arrayinc.com>
1195   Gordon McKinney          <gordon[AT]night-ray.com>
1196   Tim Farley               <tfarley[AT]iss.net>
1197   Daniel Thompson          <daniel.thompson[AT]st.com>
1198   Chris Jepeway            <thai-dragon[AT]eleven29.com>
1199   Pavel Novotny            <Pavel.Novotny[AT]icn.siemens.de>
1200
1201 Alain Magloire <alainm[AT]rcsm.ece.mcgill.ca> was kind enough to give his
1202 permission to use his version of snprintf.c.
1203
1204 Dan Lasley <dlasley[AT]promus.com> gave permission for his dumpit() hex-dump
1205 routine to be used.
1206
1207 Mattia Cazzola <mattiac[AT]alinet.it> provided a patch to the hex dump
1208 display routine.
1209
1210 We use the exception module from Kazlib, a C library written by
1211 Kaz Kylheku <kaz[AT]ashi.footprints.net>. Thanks goes to him for his
1212 well-written library. The Kazlib home page can be found at
1213 http://users.footprints.net/~kaz/kazlib.html