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
32 you interactively browse packet data from a live network or from a previously saved
33 capture file. Ethereal knows how to read B<libpcap> capture files, including those of
34 B<tcpdump>. In addition, Ethereal can read capture files from B<snoop> (including
35 B<Shomiti>), B<LanAlyzer>,
36 uncompressed B<Sniffer>, Microsoft B<Network Monitor>, AIX's B<iptrace>, B<NetXray>,
37 B<Sniffer Pro>, B<RADCOM>'s WAN/LAN analyzer, B<Lucent/Ascend> router debug output,
38 HP-UX's B<nettl>, and the dump output from B<Toshiba's> ISDN routers.
39 There is no need to tell Ethereal what type of file you
40 are reading; it will determine the file type by itself. Ethereal is also capable
41 of reading any of these file formats if they are compressed using gzip. Ethereal
42 recognizes this directly from the file; the '.gz' extension is not required for
45 Like other protocol analyzers, B<Ethereal>'s main window shows 3 views of a packet. It
46 shows a summary line, briefly describing what the packet is. A protocol tree is shown, allowing
47 you to drill down to exact protocol or field that you interested in. Finally, a hex dump
48 shows you exactly what the packet looks like when it goes over the wire.
50 In addition, B<Ethereal> has some features that make it unique. It can
51 assemble all the packets in a TCP conversation and show you the ASCII
52 (or EBCDIC) data in that conversation. Display filters in B<Ethereal>
53 are very powerful; more fields are filterable in Ethereal than in other
54 protocol analyzers, and the syntax you can use to create your filters is
55 richer. As Ethereal progresses, expect more and more protocol fields to
56 be allowed in display filters.
58 Packet capturing is performed with the pcap library. The capture filter syntax follows
59 the rules of the pcap library. This syntax is different from the display filter syntax.
61 Compressed file support uses (and therefore requires) the zlib library. If the zlib
62 library is not present, Ethereal will compile, but will be unable to read compressed files.
70 Sets the initial height of the byte view (bottom) pane.
74 Sets the name of the bold font used for the data in the byte view
75 pane that corresponds to the field selected in the protocol tree pane.
79 Sets the default number of packets to read when capturing live
84 Sets the capture filter expression.
88 Prints the version and options and exits.
92 Sets the name of the interface to use for live packet capture. It
93 should match one of the names listed in "B<netstat -i>" or "B<ifconfig -a>".
97 Starts the capture session immediately; this option requires
98 the B<-i> parameter, specifying the interface on which the capture
103 Sets the name of the font used by B<Ethereal> for most text.
107 Disables network object name resolution (such as hostname, TCP and UDP port
112 Sets the initial height of the packet list (top) pane.
116 Causes B<Ethereal> to exit after the end of capture session (useful in
117 batch mode with B<-c> option for instance); this option requires the
118 B<-i> and B<-w> parameters.
122 Reads packet data from I<file>.
126 Causes the specified filter (which uses the syntax of display filters,
127 rather than that of capture filters) to be applied, when a capture file
128 is read, to all packets read from the capture file; packets not matching
129 the filter are discarded.
133 Specifies that the live packet capture will be performed in a separate
134 process, and that the packet display will automatically be updated as
139 Sets the default snapshot length to use when capturing live data.
140 No more than I<snaplen> bytes of each network packet will be read into
141 memory, or saved to disk.
145 Sets the initial height of the tree view (middle) pane.
149 Sets the format of the packet timestamp displayed in the packet list
150 window. The format can be one of 'r' (relative), 'a' (absolute), or 'd'
151 (delta). The relative time is the time elapsed between the first packet
152 and the current packet. The absolute time is the actual date and time the
153 packet was captured. The delta time is the time since the previous packet
154 was captured. The default is relative.
158 Prints the version and exits.
162 Sets the default capture file name.
172 =item File:Open, File:Close, File:Reload
174 Open, close, or reload a capture file. The I<File:Open> dialog box
175 allows a filter to be specified; when the capture file is read, the
176 filter is applied to all packets read from the file, and packets not
177 matching the filter are discarded.
181 Prints, for all the packets in the current capture, the packet number,
182 followed by a description of each protocol header found in the packet,
183 followed by the packet data itself. Printing options can be set with the
184 I<Edit:Preferences> menu item, or in the dialog box popped up by this
187 =item File:Print Packet
189 Print a description of each protocol header found in the packet, followed
190 by the packet data itself. Printing options can be set with the
191 I<Edit:Preferences> menu item.
195 Exits the application.
197 =item Edit:Preferences
199 Sets the packet printing and filter options (see L<"Preferences"> below).
203 Initiates a live packet capture (see L<"Capture Preferences"> below).
204 A temporary file will be created to hold the capture. The location of the
205 file can be chosen by setting your TMPDIR environment variable before
206 starting ethereal. Otherwise, the default TMPDIR location is system-dependent,
207 but is likely either /var/tmp or /tmp.
209 =item Display:Options
211 Sets the format of the packet timestamp displayed in the packet list
212 window to relative, absolute, or delta.
213 Allows you to enable the automatic scrolling of the packet list while a
214 live capture is in progress.
216 =item Display:Match Selected
218 Creates and applies a display filter based on the data that is currently
219 highlighted in the protocol tree. The display filter is based on absolute
220 offset within the packet, so could be unreliable if the packet contains
221 protocols with variable-length headers, like source-routed token-ring.
223 =item Display:Colorize Display
225 Allows you to change the foreground and background colors of the packet
226 information in the list of packets, based upon display filters. The list
227 of display filters is applied to each packet sequentially. After the first
228 display filter matches a packet, any additional display filters in the list
229 are ignored. Therefore, if you are filtering on the existence of protocols,
230 you should list the higher-level protocols first, and the lower-level
233 =item Display:Find Frame
235 Allows you to search forward or backward, starting with the currently
236 selected packet (or the most recently selected packet, if no packet is
237 selected), for a packet matching a given display filter.
239 =item Display:Go To Frame
241 Allows you to go to a particular numbered packet.
243 =item Display:Collapse All
245 Collapses the protocol tree branches.
247 =item Display:Expand All
249 Expands all branches of the protocol tree.
251 =item Tools:Follow TCP Stream
253 If you have a TCP packet selected, it will display the contents of the
254 data stream for the TCP connection to which that packet belongs, as
255 text, in a separate window, and will leave the list of packets in a
256 filtered state, with only those packets that are part of that TCP
257 connection being displayed. You can revert to your old view by pressing
258 ENTER in the display filter text box, thereby invoking your old display
259 filter (or resetting it back to no display filter).
261 The window in which the data stream is displayed lets you select whether
262 the data being displayed is to be treated as ASCII or EBCDIC text, and
263 lets you print the text, using the same print options that are used for
264 the I<File:Print Packet> menu item.
274 The main window is split into three panes. You can resize each pane using
275 a "thumb" at the right end of each divider line. Below the panes is a
276 strip that shows the file load progress, current filter, and informational
279 The top pane contains the list of network packets that you can scroll
280 through and select. The packet number, packet timestamp, source and
281 destination addresses, protocol, and description are printed for each
282 packet. An effort is made to display information as high up the protocol
283 stack as possible, e.g. IP addresses are displayed for IP packets, but the
284 MAC layer address is displayed for unknown packet types.
286 The middle pane contains a I<protocol tree> for the currently-selected
287 packet. The tree displays each field and its value in each protocol header
290 The lowest pane contains a hex dump of the actual packet data.
291 Selecting a field in the I<protocol tree> highlights the corresponding
292 bytes in this section.
294 A display filter can be entered into the strip at the bottom.
295 A filter for HTTP, HTTPS, and DNS traffic might look like this:
297 tcp.port == 80 || tcp.port == 443 || tcp.port == 53
299 Selecting the I<Filter:> button lets you choose from a list of named
300 filters that you can optionally save. Pressing the Return or Enter
301 keys will cause the filter to be applied to the current list of packets.
302 Selecting the I<Reset> button clears the display filter so that all
303 packets are displayed.
307 The I<Preferences> dialog lets you select the output format of packets
308 printed using the I<File:Print Packet> menu item and configure
309 commonly-used filters.
313 =item Printing Preferences
315 The radio buttons at the top of the I<Printing> page allow you choose
316 between printing the packets as text or PostScript, and sending the
317 output directly to a command or saving it to a file. The I<Command:> text
318 entry box is the command to send files to (usually B<lpr>), and the
319 I<File:> entry box lets you enter the name of the file you wish to save
320 to. Additinally, you can select the I<File:> button to browse the file
321 system for a particular save file.
323 =item Filter Preferences
325 The I<Filters> page lets you create and modify filters, and set the
326 default filter to use when capturing data or opening a capture file.
328 The I<Filter name> entry specifies a descriptive name for a filter, e.g.
329 B<Web and DNS traffic>. The I<Filter string> entry is the text that
330 actually describes the filtering action to take, as described above.The
331 dialog buttons perform the following actions:
337 If there is text in the two entry boxes, it creates a new associated list
342 Modifies the currently selected list item to match what's in the entry
347 Makes a copy of the currently selected list item.
351 Deletes the currently selected list item.
355 Sets the currently selected list item as the active filter. If nothing
356 is selected, turns filtering off.
360 Saves the current filter list in F<$HOME/.ethereal/filters>.
364 Closes the dialog without making any changes.
368 =item Column Preferences
370 The I<Columns> page lets you specify the number, title, and format
371 of each column in the packet list.
373 The I<Column title> entry is used to specify the title of the column
374 displayed at the top of the packet list. The type of data that the column
375 displays can be specified using the I<Column format> option menu. The row
376 of buttons on the left perform the following actions:
382 Adds a new column to the list.
386 Modifies the currently selected list item.
390 Deletes the currently selected list item.
394 Moves the selected list item up or down one position.
398 Currently has no effect.
402 Saves the current column format as the default.
406 Closes the dialog without making any changes.
412 =item Capture Preferences
414 The I<Capture Preferences> dialog lets you specify various parameters for
415 capturing live packet data.
417 The I<Interface:> combo box lets you specify the interface from which to
418 capture packet data. The I<Count:> entry specifies the number of packets
419 to capture. Entering 0 will capture packets indefinitely. The I<Filter:>
420 entry lets you specify the capture filter using a tcpdump-style filter
421 string as described above. The I<File:> entry specifies the file to save
422 to, as in the I<Printer Options> dialog above. You can specify the
423 maximum number of bytes to capture per packet with the I<Capture length>
424 entry, and can specify that the display should be updated as packets are
425 captured with the I<Update list of packets in real time> check box.
427 =item Display Options
429 The I<Display Options> dialog lets you specify the format of the time stamp
430 in the packet list. You can select "Time of day" for absolute time stamps,
431 "Seconds since beginning of capture" for relative time stamps, or
432 "Seconds since previous frame" for delta time stamps. You can also
433 specify whether, when the display is updated as packets are captured,
434 the list should automatically scroll to show the most recently captured
439 =head1 CAPTURE FILTER SYNTAX
441 See manual page of tcpdump(8).
443 =head1 DISPLAY FILTER SYNTAX
445 Display filters help you remove the noise from a packet trace and let you see only
446 the packets that interest you. If a packet meets the requirements expressed in your
447 display filter, then it is displayed in the list of packets. Display filters let
448 you compare the fields within a protocol against a specific value, compare fields
449 against fields, and to check the existence of specified fields or protocols.
451 The simplest display filter allows you to check for the existence of a protocol or
452 field. If you want to see all packets which contain the IPX protocol, the filter would be
453 "ipx". (Without the quotation marks) To see all packets that contain a
454 Token-Ring RIF field, use "tr.rif".
456 Fields can also be compared against values. The comparison operators can be expressed
457 either through C-like symbols, or through English-like abbreviations:
463 ge, >= Greater than or Equal to
464 le, <= Less than or Equal to
466 Furthermore, each protocol field is typed. The types are:
468 Unsigned integer (either 8-bit, 16-bit, 24-bit, or 32-bit)
469 Signed integer (either 8-bit, 16-bit, 24-bit, or 32-bit)
471 Ethernet address (6 bytes)
472 Byte string (n-number of bytes)
477 Double-precision floating point number
479 An integer may be expressed in decimal, octal, or hexadecimal notation. The following
480 three display filters are equivalent:
486 Boolean values are either true or false. However, a boolean field is present in a
487 protocol decode only if its value is true. If the value is false, the field is not presence.
488 You can therefore check the truth value of a boolean field by simply checking for its
489 existence, that is, by naming the field. For example, a token-ring packet's source route
490 field is boolean. To find any source-routed packets, the display filter is simply:
494 Non source-routed packets can be found with the negation of that filter:
498 Ethernet addresses, as well as a string of bytes, are represented in hex digits. The hex
499 digits may be separated by colons, periods, or hyphens:
501 fddi.dst eq ff:ff:ff:ff:ff:ff
502 ipx.srcnode == 0.0.0.0.0.1
503 eth.src == aa-aa-aa-aa-aa-aa
505 If a string of bytes contains only one byte, then it is represented as an unsigned integer.
506 That is, if you are testing for hex value 'ff' in a one-byte byte-string, you must compare
507 it agains '0xff' and not 'ff'.
509 IPv4 addresses can be represented in either dotted decimal notation, or by using the hostname:
511 ip.dst eq www.mit.edu
512 ip.src == 192.168.1.1
514 IPv4 address can be compared with the same logical relations as numbers: eq, ne, gt,
515 ge, lt, and le. The IPv4 address is stored in host order, so you do not have to worry
516 about how the endianness of an IPv4 address when using it in a display filter.
518 Classless InterDomain Routing (CIDR) notation can be used to test if an IPv4 address
519 is in a certain subnet. For example, this display filter will find all packets
520 in the 129.111 Class-B network:
522 ip.addr == 129.111.0.0/16
524 Remember, the number after the slash represents the number of bits used to represent
525 the network. CIDR notation can also be used with hostnames, in this example of finding
526 IP addresses on the same Class C network as 'sneezy'
530 The CIDR notation can only be used on IP addresses or hostnames, not in variable names.
531 So, a display filter like "ip.src/24 == ip.dst/24" is not valid. (yet)
533 IPX networks are represented by unsigned 32-bit integers. Most likely you will be using
534 hexadecimal when testing for IPX network values:
536 ipx.srcnet == 0xc0a82c00
538 A substring operator also exists. You can check the substring (byte-string) of any protocol
539 or field. For example, you can filter on the vendor portion of an ethernet address (the first
540 three bytes) like this:
542 eth.src[0:3] == 00:00:83
544 Or more simply, since the number of bytes is inherent in the byte-string you provide, you
545 can provide just the offset. The previous example can be stated like this:
547 eth.src[0] == 00:00:83
549 In fact, the only time you need to explicitly provide a length is when you don't provide
550 a byte-string, and are comparing fields against fields:
552 fddi.src[0:3] == fddi.dst[0:3]
554 If the length of your byte-string is only one byte, then it must be represented in the
555 same way as an unsigned 8-bit integer:
559 You can use the substring operator on a protocol name, too. And remember, the "frame" protocol
560 encompasses the entire packet, allowing you to look at the nth byte of a packet regardless
561 of its frame type (ethernet, token-ring, etc.).
563 token[0:5] ne 0.0.0.1.1
567 Offsets for byte-strings can also be negative, in which case the negative number indicates
568 the number of bytes from the end of the field or protocol that you are testing. Here's how
569 to check the last 4 bytes of a frame:
575 frame[-4:4] == 0.1.2.3
577 All the above tests can be combined together with logical expressions. These too are expressable
578 in C-like syntax or with English-like abbreviations:
585 Expressions can be grouped by parentheses as well. The following are all valid display filter
588 tcp.port == 80 and ip.src == 192.168.2.1
590 (ipx.srcnet == 0xbad && ipx.srnode == 0.0.0.0.0.1) || ip
591 tr.dst[0:3] == 0.6.29 xor tr.src[0:3] == 0.6.29
593 A special caveat must be given regarding fields that occur more than once per packet. "ip.addr"
594 occurs twice per IP packet, once for the source address, and once for the destination address.
595 Likewise, tr.rif.ring fields can occur more than once per packet. The following two expressions
598 ip.addr ne 192.168.4.1
599 not ip.addr eq 192.168.4.1
601 The first filter says "show me all packets where an ip.addr exists that does not equal 192.168.4.1".
602 That is, as long as one ip.addr in the packet does not equal 192.168.44.1, the packet passes
603 the display filter. The second filter "don't show me any packets that have at least one ip.addr
604 field equal to 192.168.4.1". If one ip.addr is 192.168.4.1, the packet does not pass. If B<neither>
605 ip.addr fields is 192.168.4.1, then the packet passes.
607 It is easy to think of the 'ne' and 'eq' operators as having an implict "exists" modifier
608 when dealing with multiply-recurring fields. "ip.addr ne 192.168.4.1" can be thought of as
609 "there exists an ip.addr that does not equal 192.168.4.1".
611 Be careful with multiply-recurring fields; they can be confusing.
613 The following is a table of protocol and protocol fields that are filterable in Ethereal.
614 The abbreviation of the protocol or field is given. This abbreviation is what you use in
615 the display filter. The type of the field is also given.
617 =insert_dfilter_table
621 B</etc/ethers> is consulted to correlate 6-byte hardware addresses to names. If an address is not
622 found in B</etc/ethers>, the B<$HOME/.ethereal/ethers> file is consulted next. Each line
623 contains one hardware address and name, separated by whitespace.
624 The digits of the hardware address are separated by either a colon (:), a dash (-), or
625 a period (.). The following three lines are valid lines of an ethers file:
627 ff:ff:ff:ff:ff:ff Broadcast
628 c0-00-ff-ff-ff-ff TR_broadcast
629 00.00.00.00.00.00 Zero_broadcast
631 B</usr/local/etc/manuf> matches the 3-byte vendor portion of a 6-byte hardware address with
632 the manufacturer's name. The format of the file is the same as the B</etc/ethers> file,
633 except that each address is three bytes instead of six.
635 B</etc/ipxnets> and B<$HOME/.ethereal/ipxnets> correlate 4-byte IPX network numbers to names.
636 The format is the same as the B</etc/ethers> file, except that each address if four bytes
637 instead of six. Additionally, the address can be represented a single hexadecimal number,
638 as is more common in the IPX world, rather than four hex octets. For example, these four
639 lines are valid lines of an ipxnets file.
643 00:00:BE:EF IT_Server1
648 L<tcpdump(8)>, L<pcap(3)>
652 The latest version of B<ethereal> can be found at
653 B<http://ethereal.zing.org>.
659 Gerald Combs <gerald@zing.org>
664 Gilbert Ramirez <gramirez@tivoli.com>
665 Hannes R. Boehm <hannes@boehm.org>
666 Mike Hall <mlh@io.com>
667 Bobo Rajec <bobo@bsp-consulting.sk>
668 Laurent Deniel <deniel@worldnet.fr>
669 Don Lafontaine <lafont02@cn.ca>
670 Guy Harris <guy@alum.mit.edu>
671 Simon Wilkinson <sxw@dcs.ed.ac.uk>
672 Joerg Mayer <jmayer@telemation.de>
673 Martin Maciaszek <fastjack@i-s-o.net>
674 Didier Jorand <Didier.Jorand@alcatel.fr>
675 Jun-ichiro itojun Hagino <itojun@iijlab.net>
676 Richard Sharpe <sharpe@ns.aus.com>
677 John McDermott <jjm@jkintl.com>
678 Jeff Jahr <jjahr@shastanets.com>
679 Brad Robel-Forrest <bradr@watchguard.com>
680 Ashok Narayanan <ashokn@cisco.com>
681 Aaron Hillegass <aaron@classmax.com>
682 Jason Lango <jal@netapp.com>
683 Johan Feyaerts <Johan.Feyaerts@siemens.atea.be>
684 Olivier Abad <abad@daba.dhis.org>
685 Thierry Andry <Thierry.Andry@advalvas.be>
686 Jeff Foster <jjfoste@woodward.com>
687 Peter Torvals <petertv@xoommail.com>
688 Christophe Tronche <ch.tronche@computer.org>
689 Nathan Neulinger <nneul@umr.edu>
690 Tomislav Vujec <tvujec@carnet.hr>
691 Kojak <kojak@bigwig.net>
692 Uwe Girlich <Uwe.Girlich@philosys.de>
693 Warren Young <tangent@mail.com>
694 Heikki Vatiainen <hessu@cs.tut.fi>
695 Greg Hankins <gregh@twoguys.org>
697 Alain Magloire <alainm@rcsm.ece.mcgill.ca> was kind enough to give his
698 permission to use his version of snprintf.c.
700 Dan Lasley <dlasley@promus.com> gave permission for his dumpit() hex-dump