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