4 Ethereal - Interactively browse network traffic
9 S<[ B<-B> byte view height ]>
10 S<[ B<-b> bold font ]>
12 S<[ B<-f> filter expression ]>
14 S<[ B<-i> interface ]>
18 S<[ B<-P> packet list height ]>
21 S<[ B<-R> filter expression ]>
24 S<[ B<-T> tree view height ]>
25 S<[ B<-t> time stamp format ]>
31 B<Ethereal> is a GUI network protocol analyzer. It lets you
32 interactively browse packet data from a live network or from a
33 previously saved capture file. Ethereal knows how to read B<libpcap>
34 capture files, including those of B<tcpdump>. In addition, Ethereal can
35 read capture files from B<snoop> (including B<Shomiti>) and B<atmsnoop>,
36 B<LanAlyzer>, uncompressed B<Sniffer>, Microsoft B<Network Monitor>,
37 AIX's B<iptrace>, B<NetXray>, B<Sniffer Pro>, B<RADCOM>'s WAN/LAN
38 analyzer, B<Lucent/Ascend> router debug output, HP-UX's B<nettl>, and
39 the dump output from B<Toshiba's> ISDN routers. There is no need to
40 tell Ethereal what type of file you are reading; it will determine the
41 file type by itself. Ethereal is also capable of reading any of these
42 file formats if they are compressed using gzip. Ethereal recognizes
43 this directly from the file; the '.gz' extension is not required for
46 Like other protocol analyzers, B<Ethereal>'s main window shows 3 views of a packet. It
47 shows a summary line, briefly describing what the packet is. A protocol tree is shown, allowing
48 you to drill down to exact protocol or field that you interested in. Finally, a hex dump
49 shows you exactly what the packet looks like when it goes over the wire.
51 In addition, B<Ethereal> has some features that make it unique. It can
52 assemble all the packets in a TCP conversation and show you the ASCII
53 (or EBCDIC) data in that conversation. Display filters in B<Ethereal>
54 are very powerful; more fields are filterable in Ethereal than in other
55 protocol analyzers, and the syntax you can use to create your filters is
56 richer. As Ethereal progresses, expect more and more protocol fields to
57 be allowed in display filters.
59 Packet capturing is performed with the pcap library. The capture filter syntax follows
60 the rules of the pcap library. This syntax is different from the display filter syntax.
62 Compressed file support uses (and therefore requires) the zlib library. If the zlib
63 library is not present, Ethereal will compile, but will be unable to read compressed files.
71 Sets the initial height of the byte view (bottom) pane.
75 Sets the name of the bold font used for the data in the byte view
76 pane that corresponds to the field selected in the protocol tree pane.
80 Sets the default number of packets to read when capturing live
85 Sets the capture filter expression.
89 Prints the version and options and exits.
93 Sets the name of the interface to use for live packet capture. It
94 should match one of the names listed in "B<netstat -i>" or "B<ifconfig -a>".
98 Starts the capture session immediately; this option requires
99 the B<-i> parameter, specifying the interface on which the capture
104 Sets the name of the font used by B<Ethereal> for most text.
108 Disables network object name resolution (such as hostname, TCP and UDP port
113 Sets the initial height of the packet list (top) pane.
117 Causes B<Ethereal> to exit after the end of capture session (useful in
118 batch mode with B<-c> option for instance); this option requires the
119 B<-i> and B<-w> parameters.
123 Reads packet data from I<file>.
127 Causes the specified filter (which uses the syntax of display filters,
128 rather than that of capture filters) to be applied, when a capture file
129 is read, to all packets read from the capture file; packets not matching
130 the filter are discarded.
134 Specifies that the live packet capture will be performed in a separate
135 process, and that the packet display will automatically be updated as
140 Sets the default snapshot length to use when capturing live data.
141 No more than I<snaplen> bytes of each network packet will be read into
142 memory, or saved to disk.
146 Sets the initial height of the tree view (middle) pane.
150 Sets the format of the packet timestamp displayed in the packet list
151 window. The format can be one of 'r' (relative), 'a' (absolute), or 'd'
152 (delta). The relative time is the time elapsed between the first packet
153 and the current packet. The absolute time is the actual date and time the
154 packet was captured. The delta time is the time since the previous packet
155 was captured. The default is relative.
159 Prints the version and exits.
163 Sets the default capture file name.
173 =item File:Open, File:Close, File:Reload
175 Open, close, or reload a capture file. The I<File:Open> dialog box
176 allows a filter to be specified; when the capture file is read, the
177 filter is applied to all packets read from the file, and packets not
178 matching the filter are discarded.
180 =item File:Save, File:Save As
182 Save the current capture, or the packets currently displayed from that
183 capture, to a file. A check box lets you select whether to save all
184 packets, or just those that have passed the current display filter, and
185 an option menu lets you select (from a list of file formats in which at
186 particular capture, or the packets currently displayed from that
187 capture, can be saved), a file format in which to save it.
191 Prints, for all the packets in the current capture, the packet number,
192 followed by a description of each protocol header found in the packet,
193 followed by the packet data itself. Printing options can be set with the
194 I<Edit:Preferences> menu item, or in the dialog box popped up by this
197 =item File:Print Packet
199 Print a description of each protocol header found in the packet, followed
200 by the packet data itself. Printing options can be set with the
201 I<Edit:Preferences> menu item.
205 Exits the application.
207 =item Edit:Preferences
209 Sets the packet printing and filter options (see L<"Preferences"> below).
213 Initiates a live packet capture (see L<"Capture Preferences"> below).
214 A temporary file will be created to hold the capture. The location of the
215 file can be chosen by setting your TMPDIR environment variable before
216 starting ethereal. Otherwise, the default TMPDIR location is system-dependent,
217 but is likely either /var/tmp or /tmp.
219 =item Display:Options
221 Sets the format of the packet timestamp displayed in the packet list
222 window to relative, absolute, or delta.
223 Allows you to enable the automatic scrolling of the packet list while a
224 live capture is in progress.
226 =item Display:Match Selected
228 Creates and applies a display filter based on the data that is currently
229 highlighted in the protocol tree. If that data is a field that can be
230 tested in a display filter expression, the display filter will test that
231 field; otherwise, the display filter will be based on absolute offset
232 within the packet, and so could be unreliable if the packet contains
233 protocols with variable-length headers, such as a source-routed
236 =item Display:Colorize Display
238 Allows you to change the foreground and background colors of the packet
239 information in the list of packets, based upon display filters. The list
240 of display filters is applied to each packet sequentially. After the first
241 display filter matches a packet, any additional display filters in the list
242 are ignored. Therefore, if you are filtering on the existence of protocols,
243 you should list the higher-level protocols first, and the lower-level
246 =item Display:Find Frame
248 Allows you to search forward or backward, starting with the currently
249 selected packet (or the most recently selected packet, if no packet is
250 selected), for a packet matching a given display filter.
252 =item Display:Go To Frame
254 Allows you to go to a particular numbered packet.
256 =item Display:Collapse All
258 Collapses the protocol tree branches.
260 =item Display:Expand All
262 Expands all branches of the protocol tree.
264 =item Tools:Follow TCP Stream
266 If you have a TCP packet selected, it will display the contents of the
267 data stream for the TCP connection to which that packet belongs, as
268 text, in a separate window, and will leave the list of packets in a
269 filtered state, with only those packets that are part of that TCP
270 connection being displayed. You can revert to your old view by pressing
271 ENTER in the display filter text box, thereby invoking your old display
272 filter (or resetting it back to no display filter).
274 The window in which the data stream is displayed lets you select whether
275 the data being displayed is to be treated as ASCII or EBCDIC text, and
276 lets you print the text, using the same print options that are used for
277 the I<File:Print Packet> menu item.
287 The main window is split into three panes. You can resize each pane using
288 a "thumb" at the right end of each divider line. Below the panes is a
289 strip that shows the file load progress, current filter, and informational
292 The top pane contains the list of network packets that you can scroll
293 through and select. The packet number, packet timestamp, source and
294 destination addresses, protocol, and description are printed for each
295 packet. An effort is made to display information as high up the protocol
296 stack as possible, e.g. IP addresses are displayed for IP packets, but the
297 MAC layer address is displayed for unknown packet types.
299 The middle pane contains a I<protocol tree> for the currently-selected
300 packet. The tree displays each field and its value in each protocol header
303 The lowest pane contains a hex dump of the actual packet data.
304 Selecting a field in the I<protocol tree> highlights the corresponding
305 bytes in this section.
307 A display filter can be entered into the strip at the bottom.
308 A filter for HTTP, HTTPS, and DNS traffic might look like this:
310 tcp.port == 80 || tcp.port == 443 || tcp.port == 53
312 Selecting the I<Filter:> button lets you choose from a list of named
313 filters that you can optionally save. Pressing the Return or Enter
314 keys will cause the filter to be applied to the current list of packets.
315 Selecting the I<Reset> button clears the display filter so that all
316 packets are displayed.
320 The I<Preferences> dialog lets you select the output format of packets
321 printed using the I<File:Print Packet> menu item and configure
322 commonly-used filters.
326 =item Printing Preferences
328 The radio buttons at the top of the I<Printing> page allow you choose
329 between printing the packets as text or PostScript, and sending the
330 output directly to a command or saving it to a file. The I<Command:> text
331 entry box is the command to send files to (usually B<lpr>), and the
332 I<File:> entry box lets you enter the name of the file you wish to save
333 to. Additinally, you can select the I<File:> button to browse the file
334 system for a particular save file.
336 =item Filter Preferences
338 The I<Filters> page lets you create and modify filters, and set the
339 default filter to use when capturing data or opening a capture file.
341 The I<Filter name> entry specifies a descriptive name for a filter, e.g.
342 B<Web and DNS traffic>. The I<Filter string> entry is the text that
343 actually describes the filtering action to take, as described above.The
344 dialog buttons perform the following actions:
350 If there is text in the two entry boxes, it creates a new associated list
355 Modifies the currently selected list item to match what's in the entry
360 Makes a copy of the currently selected list item.
364 Deletes the currently selected list item.
368 Sets the currently selected list item as the active filter. If nothing
369 is selected, turns filtering off.
373 Saves the current filter list in F<$HOME/.ethereal/filters>.
377 Closes the dialog without making any changes.
381 =item Column Preferences
383 The I<Columns> page lets you specify the number, title, and format
384 of each column in the packet list.
386 The I<Column title> entry is used to specify the title of the column
387 displayed at the top of the packet list. The type of data that the column
388 displays can be specified using the I<Column format> option menu. The row
389 of buttons on the left perform the following actions:
395 Adds a new column to the list.
399 Modifies the currently selected list item.
403 Deletes the currently selected list item.
407 Moves the selected list item up or down one position.
411 Currently has no effect.
415 Saves the current column format as the default.
419 Closes the dialog without making any changes.
427 The I<TCP Streams> page can be used to change the color of the text
428 displayed in the TCP stream window. To change a color, simply select
429 an attribute from the "Set:" menu and use the color selector to get the
430 desired color. The new text colors are displayed in a sample window.
432 =item Capture Preferences
434 The I<Capture Preferences> dialog lets you specify various parameters for
435 capturing live packet data.
437 The I<Interface:> combo box lets you specify the interface from which to
438 capture packet data. The I<Count:> entry specifies the number of packets
439 to capture. Entering 0 will capture packets indefinitely. The I<Filter:>
440 entry lets you specify the capture filter using a tcpdump-style filter
441 string as described above. The I<File:> entry specifies the file to save
442 to, as in the I<Printer Options> dialog above. You can specify the
443 maximum number of bytes to capture per packet with the I<Capture length>
444 entry, and can specify that the display should be updated as packets are
445 captured with the I<Update list of packets in real time> check box.
447 =item Display Options
449 The I<Display Options> dialog lets you specify the format of the time stamp
450 in the packet list. You can select "Time of day" for absolute time stamps,
451 "Seconds since beginning of capture" for relative time stamps, or
452 "Seconds since previous frame" for delta time stamps. You can also
453 specify whether, when the display is updated as packets are captured,
454 the list should automatically scroll to show the most recently captured
459 =head1 CAPTURE FILTER SYNTAX
461 See manual page of tcpdump(8).
463 =head1 DISPLAY FILTER SYNTAX
465 Display filters help you remove the noise from a packet trace and let you see only
466 the packets that interest you. If a packet meets the requirements expressed in your
467 display filter, then it is displayed in the list of packets. Display filters let
468 you compare the fields within a protocol against a specific value, compare fields
469 against fields, and to check the existence of specified fields or protocols.
471 The simplest display filter allows you to check for the existence of a protocol or
472 field. If you want to see all packets which contain the IPX protocol, the filter would be
473 "ipx". (Without the quotation marks) To see all packets that contain a
474 Token-Ring RIF field, use "tr.rif".
476 Fields can also be compared against values. The comparison operators can be expressed
477 either through C-like symbols, or through English-like abbreviations:
483 ge, >= Greater than or Equal to
484 le, <= Less than or Equal to
486 Furthermore, each protocol field is typed. The types are:
488 Unsigned integer (either 8-bit, 16-bit, 24-bit, or 32-bit)
489 Signed integer (either 8-bit, 16-bit, 24-bit, or 32-bit)
491 Ethernet address (6 bytes)
492 Byte string (n-number of bytes)
497 Double-precision floating point number
499 An integer may be expressed in decimal, octal, or hexadecimal notation. The following
500 three display filters are equivalent:
506 Boolean values are either true or false. However, a boolean field is present in a
507 protocol decode only if its value is true. If the value is false, the field is not presence.
508 You can therefore check the truth value of a boolean field by simply checking for its
509 existence, that is, by naming the field. For example, a token-ring packet's source route
510 field is boolean. To find any source-routed packets, the display filter is simply:
514 Non source-routed packets can be found with the negation of that filter:
518 Ethernet addresses, as well as a string of bytes, are represented in hex digits. The hex
519 digits may be separated by colons, periods, or hyphens:
521 fddi.dst eq ff:ff:ff:ff:ff:ff
522 ipx.srcnode == 0.0.0.0.0.1
523 eth.src == aa-aa-aa-aa-aa-aa
525 If a string of bytes contains only one byte, then it is represented as an unsigned integer.
526 That is, if you are testing for hex value 'ff' in a one-byte byte-string, you must compare
527 it agains '0xff' and not 'ff'.
529 IPv4 addresses can be represented in either dotted decimal notation, or by using the hostname:
531 ip.dst eq www.mit.edu
532 ip.src == 192.168.1.1
534 IPv4 address can be compared with the same logical relations as numbers: eq, ne, gt,
535 ge, lt, and le. The IPv4 address is stored in host order, so you do not have to worry
536 about how the endianness of an IPv4 address when using it in a display filter.
538 Classless InterDomain Routing (CIDR) notation can be used to test if an IPv4 address
539 is in a certain subnet. For example, this display filter will find all packets
540 in the 129.111 Class-B network:
542 ip.addr == 129.111.0.0/16
544 Remember, the number after the slash represents the number of bits used to represent
545 the network. CIDR notation can also be used with hostnames, in this example of finding
546 IP addresses on the same Class C network as 'sneezy'
550 The CIDR notation can only be used on IP addresses or hostnames, not in variable names.
551 So, a display filter like "ip.src/24 == ip.dst/24" is not valid. (yet)
553 IPX networks are represented by unsigned 32-bit integers. Most likely you will be using
554 hexadecimal when testing for IPX network values:
556 ipx.srcnet == 0xc0a82c00
558 A substring operator also exists. You can check the substring (byte-string) of any protocol
559 or field. For example, you can filter on the vendor portion of an ethernet address (the first
560 three bytes) like this:
562 eth.src[0:3] == 00:00:83
564 Or more simply, since the number of bytes is inherent in the byte-string you provide, you
565 can provide just the offset. The previous example can be stated like this:
567 eth.src[0] == 00:00:83
569 In fact, the only time you need to explicitly provide a length is when you don't provide
570 a byte-string, and are comparing fields against fields:
572 fddi.src[0:3] == fddi.dst[0:3]
574 If the length of your byte-string is only one byte, then it must be represented in the
575 same way as an unsigned 8-bit integer:
579 You can use the substring operator on a protocol name, too. And remember, the "frame" protocol
580 encompasses the entire packet, allowing you to look at the nth byte of a packet regardless
581 of its frame type (ethernet, token-ring, etc.).
583 token[0:5] ne 0.0.0.1.1
587 Offsets for byte-strings can also be negative, in which case the negative number indicates
588 the number of bytes from the end of the field or protocol that you are testing. Here's how
589 to check the last 4 bytes of a frame:
595 frame[-4:4] == 0.1.2.3
597 All the above tests can be combined together with logical expressions. These too are expressable
598 in C-like syntax or with English-like abbreviations:
605 Expressions can be grouped by parentheses as well. The following are all valid display filter
608 tcp.port == 80 and ip.src == 192.168.2.1
610 (ipx.srcnet == 0xbad && ipx.srnode == 0.0.0.0.0.1) || ip
611 tr.dst[0:3] == 0.6.29 xor tr.src[0:3] == 0.6.29
613 A special caveat must be given regarding fields that occur more than once per packet. "ip.addr"
614 occurs twice per IP packet, once for the source address, and once for the destination address.
615 Likewise, tr.rif.ring fields can occur more than once per packet. The following two expressions
618 ip.addr ne 192.168.4.1
619 not ip.addr eq 192.168.4.1
621 The first filter says "show me all packets where an ip.addr exists that does not equal 192.168.4.1".
622 That is, as long as one ip.addr in the packet does not equal 192.168.44.1, the packet passes
623 the display filter. The second filter "don't show me any packets that have at least one ip.addr
624 field equal to 192.168.4.1". If one ip.addr is 192.168.4.1, the packet does not pass. If B<neither>
625 ip.addr fields is 192.168.4.1, then the packet passes.
627 It is easy to think of the 'ne' and 'eq' operators as having an implict "exists" modifier
628 when dealing with multiply-recurring fields. "ip.addr ne 192.168.4.1" can be thought of as
629 "there exists an ip.addr that does not equal 192.168.4.1".
631 Be careful with multiply-recurring fields; they can be confusing.
633 The following is a table of protocol and protocol fields that are filterable in Ethereal.
634 The abbreviation of the protocol or field is given. This abbreviation is what you use in
635 the display filter. The type of the field is also given.
637 =insert_dfilter_table
641 B</etc/ethers> is consulted to correlate 6-byte hardware addresses to names. If an address is not
642 found in B</etc/ethers>, the B<$HOME/.ethereal/ethers> file is consulted next. Each line
643 contains one hardware address and name, separated by whitespace.
644 The digits of the hardware address are separated by either a colon (:), a dash (-), or
645 a period (.). The following three lines are valid lines of an ethers file:
647 ff:ff:ff:ff:ff:ff Broadcast
648 c0-00-ff-ff-ff-ff TR_broadcast
649 00.00.00.00.00.00 Zero_broadcast
651 B</usr/local/etc/manuf> matches the 3-byte vendor portion of a 6-byte hardware address with
652 the manufacturer's name. The format of the file is the same as the B</etc/ethers> file,
653 except that each address is three bytes instead of six.
655 B</etc/ipxnets> and B<$HOME/.ethereal/ipxnets> correlate 4-byte IPX network numbers to names.
656 The format is the same as the B</etc/ethers> file, except that each address if four bytes
657 instead of six. Additionally, the address can be represented a single hexadecimal number,
658 as is more common in the IPX world, rather than four hex octets. For example, these four
659 lines are valid lines of an ipxnets file.
663 00:00:BE:EF IT_Server1
668 L<tcpdump(8)>, L<pcap(3)>
672 The latest version of B<ethereal> can be found at
673 B<http://ethereal.zing.org>.
679 Gerald Combs <gerald@zing.org>
684 Gilbert Ramirez <gramirez@tivoli.com>
685 Hannes R. Boehm <hannes@boehm.org>
686 Mike Hall <mlh@io.com>
687 Bobo Rajec <bobo@bsp-consulting.sk>
688 Laurent Deniel <deniel@worldnet.fr>
689 Don Lafontaine <lafont02@cn.ca>
690 Guy Harris <guy@alum.mit.edu>
691 Simon Wilkinson <sxw@dcs.ed.ac.uk>
692 Joerg Mayer <jmayer@telemation.de>
693 Martin Maciaszek <fastjack@i-s-o.net>
694 Didier Jorand <Didier.Jorand@alcatel.fr>
695 Jun-ichiro itojun Hagino <itojun@iijlab.net>
696 Richard Sharpe <sharpe@ns.aus.com>
697 John McDermott <jjm@jkintl.com>
698 Jeff Jahr <jjahr@shastanets.com>
699 Brad Robel-Forrest <bradr@watchguard.com>
700 Ashok Narayanan <ashokn@cisco.com>
701 Aaron Hillegass <aaron@classmax.com>
702 Jason Lango <jal@netapp.com>
703 Johan Feyaerts <Johan.Feyaerts@siemens.atea.be>
704 Olivier Abad <abad@daba.dhis.net>
705 Thierry Andry <Thierry.Andry@advalvas.be>
706 Jeff Foster <jjfoste@woodward.com>
707 Peter Torvals <petertv@xoommail.com>
708 Christophe Tronche <ch.tronche@computer.org>
709 Nathan Neulinger <nneul@umr.edu>
710 Tomislav Vujec <tvujec@carnet.hr>
711 Kojak <kojak@bigwig.net>
712 Uwe Girlich <Uwe.Girlich@philosys.de>
713 Warren Young <tangent@mail.com>
714 Heikki Vatiainen <hessu@cs.tut.fi>
715 Greg Hankins <gregh@twoguys.org>
716 Jerry Talkington <jerryt@netapp.com>
717 James Coe" <jammer@cin.net>
719 Alain Magloire <alainm@rcsm.ece.mcgill.ca> was kind enough to give his
720 permission to use his version of snprintf.c.
722 Dan Lasley <dlasley@promus.com> gave permission for his dumpit() hex-dump