4 Ethereal - Interactively browse network traffic
9 S<[ B<-B> byte view height ]>
10 S<[ B<-b> bold font ]>
13 S<[ B<-f> filter expression ]>
15 S<[ B<-i> interface ]>
19 S<[ B<-P> packet list height ]>
22 S<[ B<-R> filter expression ]>
25 S<[ B<-T> tree view height ]>
26 S<[ B<-t> time stamp format ]>
32 B<Ethereal> is a GUI network protocol analyzer. It lets
33 you interactively browse packet data from a live network or from a previously saved
34 capture file. Ethereal knows how to read B<libpcap> capture files, including those of
35 B<tcpdump>. In addition, Ethereal can read capture files from B<snoop> (including
36 B<Shomiti>), B<LanAlyzer>,
37 uncompressed B<Sniffer>, Microsoft B<Network Monitor>, AIX's B<iptrace>, B<NetXray>,
38 B<Sniffer Pro>, and B<RADCOM>'s WAN/LAN analyzer.
39 There is no need to tell Ethereal what type of file you
40 are reading; it will determine the file type by itself.
42 Like other protocol analyzers, B<Ethereal>'s main window shows 3 views of a packet. It
43 shows a summary line, briefly describing what the packet is. A protocol tree is shown, allowing
44 you to drill down to exact protocol or field that you interested in. Finally, a hex dump
45 shows you exactly what the packet looks like when it goes over the wire.
47 In addition, B<Ethereal> has some features that make it unique. It can assemble all
48 the packets in a TCP conversation and show you the ASCII data in that conversation. Display
49 filters in B<Ethereal> are very powerful; more fields are filterable in Ethereal than in other
50 protocol analyzers, and the syntax you can use to create your filters is richer. As Ethereal
51 progresses, expect more and more protocol fields to be allowed in display filters.
53 Packet capturing is performed with the pcap library. The capture filter syntax follows
54 the rules of the pcap library. This syntax is different from the display filter syntax.
62 Sets the initial height of the byte view (bottom) pane.
66 Sets the name of the bold font used for the data in the byte view
67 pane that corresponds to the field selected in the protocol tree pane.
71 Sets the default number of packets to read when capturing live
76 Specifies that the live packet capture will be performed in a separate
77 process. It is then possible to open/reload the file to display the
78 packets actually captured.
82 Sets the capture filter expression.
86 Prints the version and options and exits.
90 Sets the name of the interface to use for live packet capture. It
91 should match one of the names listed in "B<netstat -i>" or "B<ifconfig -a>".
95 Starts the capture session immediately; this option requires
96 the B<-i> and B<-w> parameters.
100 Sets the name of the font used by B<Ethereal> for most text.
104 Disables network object name resolution (such as hostname, TCP and UDP port
109 Sets the initial height of the packet list (top) pane.
113 Causes B<Ethereal> to exit after the end of capture session (useful in
114 batch mode with B<-c> option for instance); this option requires the
115 B<-i> and B<-w> parameters.
119 Reads packet data from I<file>.
123 Causes the specified filter (which uses the syntax of display filters,
124 rather than that of capture filters) to be applied, when a capture file
125 is read, to all packets read from the capture file; packets not matching
126 the filter are discarded.
130 Specifies that the live packet capture will be performed in a separate
131 process (same as option B<-F>) and that the packet displaying should be
132 synchronized with the capture session without human operation
133 (i.e. without load/reload). This is an experimental feature.
137 Sets the default snapshot length to use when capturing live data.
138 No more than I<snaplen> bytes of each network packet will be read into
139 memory, or saved to disk.
143 Sets the initial height of the tree view (middle) pane.
147 Sets the format of the packet timestamp displayed in the packet list
148 window. The format can be one of 'r' (relative), 'a' (absolute), or 'd'
149 (delta). The relative time is the time elapsed between the first packet
150 and the current packet. The absolute time is the actual date and time the
151 packet was captured. The delta time is the time since the previous packet
152 was captured. The default is relative.
156 Prints the version and exits.
160 Sets the default capture file name.
170 =item File:Open, File:Close, File:Reload
172 Open, close, or reload a capture file. The I<File:Open> dialog box
173 allows a filter to be specified; when the capture file is read, the
174 filter is applied to all packets read from the file, and packets not
175 matching the filter are discarded.
179 Prints, for all the packets in the current capture, the packet number,
180 followed by a description of each protocol header found in the packet,
181 followed by the packet data itself. Printing options can be set with the
182 I<Edit:Preferences> menu item, or in the dialog box popped up by this
185 =item File:Print Packet
187 Print a description of each protocol header found in the packet, followed
188 by the packet data itself. Printing options can be set with the
189 I<Edit:Preferences> menu item.
193 Exits the application.
195 =item Edit:Preferences
197 Sets the packet printing and filter options (see L<"Preferences"> below).
201 Initiates a live packet capture (see L<"Capture Preferences"> below).
202 A temporary file will be created to hold the capture. The location of the
203 file can be chosen by setting your TMPDIR environment variable before
204 starting ethereal. Otherwise, the default TMPDIR location is system-dependent,
205 but is likely either /var/tmp or /tmp.
207 =item Display:Options
209 Sets the format of the packet timestamp displayed in the packet list
210 window to relative, absolute, or delta.
212 =item Tools:Follow TCP Stream
214 If you have a TCP packet selected, it will display the contents of the TCP
215 data stream in a separate window. This has the side-effect of leaving
216 the list of packets in a filtered state; only those packets that make up
217 the TCP stream are shown. You can revert to your old view by pressing
218 ENTER in the display filter text box, thereby invoking your old
219 display filter (or resetting it back to no display filter).
229 The main window is split into three panes. You can resize each pane using
230 a "thumb" at the right end of each divider line. Below the panes is a
231 strip that shows the file load progress, current filter, and informational
234 The top pane contains the list of network packets that you can scroll
235 through and select. The packet number, packet timestamp, source and
236 destination addresses, protocol, and description are printed for each
237 packet. An effort is made to display information as high up the protocol
238 stack as possible, e.g. IP addresses are displayed for IP packets, but the
239 MAC layer address is displayed for unknown packet types.
241 The middle pane contains a I<protocol tree> for the currently-selected
242 packet. The tree displays each field and its value in each protocol header
245 The lowest pane contains a hex dump of the actual packet data.
246 Selecting a field in the I<protocol tree> highlights the corresponding
247 bytes in this section.
249 A display filter can be entered into the strip at the bottom.
250 A filter for HTTP, HTTPS, and DNS traffic might look like this:
252 tcp.port == 80 || tcp.port == 443 || tcp.port == 53
254 Selecting the I<Filter:> button lets you choose from a list of named
255 filters that you can optionally save. Pressing the Return or Enter
256 keys will cause the filter to be applied to the current list of packets.
260 The I<Preferences> dialog lets you select the output format of packets
261 printed using the I<File:Print Packet> menu item and configure
262 commonly-used filters.
266 =item Printing Preferences
268 The radio buttons at the top of the I<Printing> page allow you choose
269 between printing the packets as text or PostScript, and sending the
270 output directly to a command or saving it to a file. The I<Command:> text
271 entry box is the command to send files to (usually B<lpr>), and the
272 I<File:> entry box lets you enter the name of the file you wish to save
273 to. Additinally, you can select the I<File:> button to browse the file
274 system for a particular save file.
276 =item Filter Preferences
278 The I<Filters> page lets you create and modify filters, and set the
279 default filter to use when capturing data or opening a capture file.
281 The I<Filter name> entry specifies a descriptive name for a filter, e.g.
282 B<Web and DNS traffic>. The I<Filter string> entry is the text that
283 actually describes the filtering action to take, as described above.The
284 dialog buttons perform the following actions:
290 If there is text in the two entry boxes, it creates a new associated list
295 Modifies the currently selected list item to match what's in the entry
300 Makes a copy of the currently selected list item.
304 Deletes the currently selected list item.
308 Sets the currently selected list item as the active filter. If nothing
309 is selected, turns filtering off.
313 Saves the current filter list in F<$HOME/.ethereal/filters>.
317 Closes the dialog without making any changes.
321 =item Column Preferences
323 The I<Columns> page lets you specify the number, title, and format
324 of each column in the packet list.
326 The I<Column title> entry is used to specify the title of the column
327 displayed at the top of the packet list. The type of data that the column
328 displays can be specified using the I<Column format> option menu. The row
329 of buttons on the left perform the following actions:
335 Adds a new column to the list.
339 Modifies the currently selected list item.
343 Deletes the currently selected list item.
347 Moves the selected list item up or down one position.
351 Currently has no effect.
355 Saves the current column format as the default.
359 Closes the dialog without making any changes.
365 =item Capture Preferences
367 The I<Capture Preferences> dialog lets you specify various parameters for
368 capturing live packet data.
370 The I<Interface:> entry box lets you specify the interface from which to
371 capture packet data. The I<Count:> entry specifies the number of packets
372 to capture. Entering 0 will capture packets indefinitely. The I<Filter:>
373 entry lets you specify the capture filter using a tcpdump-style filter
374 string as described above. The I<File:> entry specifies the file to save
375 to, as in the I<Printer Options> dialog above. You can choose to open the
376 file after capture, and you can also specify the maximum number of bytes
377 to capture per packet with the I<Capture length> entry.
379 =item Display Options
381 The I<Display Options> dialog lets you specify the format of the time stamp
382 in the packet list. You can select "Time of day" for absolute time stamps,
383 "Seconds since beginning of capture" for relative time stamps, or
384 "Seconds since previous frame" for delta time stamps.
388 =head1 DISPLAY FILTER SYNTAX
390 Display filters help you remove the noise from a packet trace and let you see only
391 the packets that interest you. If a packet meets the requirements expressed in your
392 display filter, then it is displayed in the list of packets. Display filters let
393 you compare the fields within a protocol against a specific value, compare fields
394 against fields, and to check the existence of specified fields or protocols.
396 The simplest display filter allows you to check for the existence of a protocol or
397 field. If you want to see all packets which contain the IPX protocol, the filter would be
398 "ipx". (Without the quotation marks) To see all packets that contain a
399 Token-Ring RIF field, use "tr.rif".
401 Fields can also be compared against values. The comparison operators can be expressed
402 either through C-like symbols, or through English-like abbreviations:
408 ge, >= Greater than or Equal to
409 le, <= Less than or Equal to
411 Furthermore, each protocol field is typed. The types are:
413 Unsigned integer (either 8-bit, 16-bit, or 32-bit)
414 Boolean (true or false)
415 Ethernet address (6 bytes)
416 Byte string (n-number of bytes)
420 An integer may be expressed in decimal, octal, or hexadecimal notation. The following
421 three display filters are equivalent:
427 Boolean values are either true or false. For example, a token-ring packet's source route
432 Ethernet addresses, as well as a string of bytes, are represented in hex digits. The hex
433 digits may be separated by colons, periods, or hyphens:
435 fddi.dst eq ff:ff:ff:ff:ff:ff
436 ipx.srcnode == 0.0.0.0.0.1
437 ether.src == aa-aa-aa-aa-aa-aa
439 If a string of bytes contains only one byte, then it is represented as an unsigned integer.
440 That is, if you are testing for hex value 'ff' in a one-byte byte-string, you must compare
441 it agains '0xff' and not 'ff'.
443 IPv4 addresses can be represented in either dotted decimal notation, or by using the hostname:
445 ip.dst eq www.mit.edu
446 ip.src == 192.168.1.1
448 IPX networks are represented by unsigned 32-bit integers. Most likely you will be using
449 hexadecimal when testing for IPX network values:
451 ipx.srcnet == 0xc0a82c00
453 A substring operator also exists. You can check the substring (byte-string) of any protocol
454 or field. For example, you can filter on the vendor portion of an ethernet address (the first
455 three bytes) like this:
457 ether.src[0:3] == 00:00:83
459 You can use the substring operator on a protocol name, too. And remember, the "frame" protocol
460 encompasses the entire packet, allowing you to look at the nth byte of a packet regardless
461 of its frame type (ethernet, token-ring, etc.).
463 token[0:5] ne 0.0.0.1.1
467 The above tests can be combined together with logical expressions. These too are expressable
468 in C-like syntax or with English-like abbreviations:
475 Expressions can be grouped by parentheses as well. The following are all valid display filter
478 tcp.port == 80 and ip.src == 192.168.2.1
480 (ipx.srcnet == 0xbad && ipx.srnode == 0.0.0.0.0.1) || ip
481 tr.dst[0:3] == 0.6.29 xor tr.src[0:3] == 0.6.29
483 A special caveat must be given regarding fields that occur more than once per packet. "ip.addr"
484 occurs twice per IP packet, once for the source address, and once for the destination address.
485 Likewise, tr.rif.ring fields can occur more than once per packet. The following two expressions
488 ip.addr ne 192.168.4.1
489 not ip.addr eq 192.168.4.1
491 The first filter says "show me all packets where an ip.addr exists that does not equal 192.168.4.1".
492 That is, as long as one ip.addr in the packet does not equal 192.168.44.1, the packet passes
493 the display filter. The second filter "don't show me any packets that have at least one ip.addr
494 field equal to 192.168.4.1". If one ip.addr is 192.168.4.1, the packet does not pass. If B<neither>
495 ip.addr fields is 192.168.4.1, then the packet passes.
497 It is easy to think of the 'ne' and 'eq' operators as having an implict "exists" modifier
498 when dealing with multiply-recurring fields. "ip.addr ne 192.168.4.1" can be thought of as
499 "there exists an ip.addr that does not equal 192.168.4.1".
501 Be careful with multiply-recurring fields; they can be confusing.
503 The following is a table of protocol and protocol fields that are filterable in Ethereal.
504 The abbreviation of the protocol or field is given. This abbreviation is what you use in
505 the display filter. The type of the field is also given.
507 =insert_dfilter_table
511 L<tcpdump(8)>, L<pcap(3)>
515 The latest version of B<ethereal> can be found at
516 B<http://ethereal.zing.org>.
522 Gerald Combs <gerald@zing.org>
527 Gilbert Ramirez <gramirez@tivoli.com>
528 Hannes R. Boehm <hannes@boehm.org>
529 Mike Hall <mlh@io.com>
530 Bobo Rajec <bobo@bsp-consulting.sk>
531 Laurent Deniel <deniel@worldnet.fr>
532 Don Lafontaine <lafont02@cn.ca>
533 Guy Harris <guy@netapp.com>
534 Simon Wilkinson <sxw@dcs.ed.ac.uk>
535 Joerg Mayer <jmayer@telemation.de>
536 Martin Maciaszek <fastjack@i-s-o.net>
537 Didier Jorand <Didier.Jorand@alcatel.fr>
538 Jun-ichiro itojun Hagino <itojun@iijlab.net>
539 Richard Sharpe <sharpe@ns.aus.com>
540 John McDermott <jjm@jkintl.com>
541 Jeff Jahr <jjahr@shastanets.com>
542 Brad Robel-Forrest <bradr@watchguard.com>
543 Ashok Narayanan <ashokn@cisco.com>
544 Aaron Hillegass <aaron@classmax.com>
545 Jason Lango <jal@netapp.com>
546 Johan Feyaerts <Johan.Feyaerts@siemens.atea.be>
547 Olivier Abad <abad@daba.dhis.org>
548 Thierry Andry <Thierry.Andry@advalvas.be>
549 Jeff Foster <jjfoste@woodward.com>
551 Alain Magloire <alainm@rcsm.ece.mcgill.ca> was kind enough to give his
552 permission to use his version of snprintf.c.
554 Dan Lasley <dlasley@promus.com> gave permission for his dumpit() hex-dump