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