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.
305 The I<Preferences> dialog lets you select the output format of packets
306 printed using the I<File:Print Packet> menu item and configure
307 commonly-used filters.
311 =item Printing Preferences
313 The radio buttons at the top of the I<Printing> page allow you choose
314 between printing the packets as text or PostScript, and sending the
315 output directly to a command or saving it to a file. The I<Command:> text
316 entry box is the command to send files to (usually B<lpr>), and the
317 I<File:> entry box lets you enter the name of the file you wish to save
318 to. Additinally, you can select the I<File:> button to browse the file
319 system for a particular save file.
321 =item Filter Preferences
323 The I<Filters> page lets you create and modify filters, and set the
324 default filter to use when capturing data or opening a capture file.
326 The I<Filter name> entry specifies a descriptive name for a filter, e.g.
327 B<Web and DNS traffic>. The I<Filter string> entry is the text that
328 actually describes the filtering action to take, as described above.The
329 dialog buttons perform the following actions:
335 If there is text in the two entry boxes, it creates a new associated list
340 Modifies the currently selected list item to match what's in the entry
345 Makes a copy of the currently selected list item.
349 Deletes the currently selected list item.
353 Sets the currently selected list item as the active filter. If nothing
354 is selected, turns filtering off.
358 Saves the current filter list in F<$HOME/.ethereal/filters>.
362 Closes the dialog without making any changes.
366 =item Column Preferences
368 The I<Columns> page lets you specify the number, title, and format
369 of each column in the packet list.
371 The I<Column title> entry is used to specify the title of the column
372 displayed at the top of the packet list. The type of data that the column
373 displays can be specified using the I<Column format> option menu. The row
374 of buttons on the left perform the following actions:
380 Adds a new column to the list.
384 Modifies the currently selected list item.
388 Deletes the currently selected list item.
392 Moves the selected list item up or down one position.
396 Currently has no effect.
400 Saves the current column format as the default.
404 Closes the dialog without making any changes.
410 =item Capture Preferences
412 The I<Capture Preferences> dialog lets you specify various parameters for
413 capturing live packet data.
415 The I<Interface:> combo box lets you specify the interface from which to
416 capture packet data. The I<Count:> entry specifies the number of packets
417 to capture. Entering 0 will capture packets indefinitely. The I<Filter:>
418 entry lets you specify the capture filter using a tcpdump-style filter
419 string as described above. The I<File:> entry specifies the file to save
420 to, as in the I<Printer Options> dialog above. You can specify the
421 maximum number of bytes to capture per packet with the I<Capture length>
422 entry, and can specify that the display should be updated as packets are
423 captured with the I<Update list of packets in real time> check box.
425 =item Display Options
427 The I<Display Options> dialog lets you specify the format of the time stamp
428 in the packet list. You can select "Time of day" for absolute time stamps,
429 "Seconds since beginning of capture" for relative time stamps, or
430 "Seconds since previous frame" for delta time stamps. You can also
431 specify whether, when the display is updated as packets are captured,
432 the list should automatically scroll to show the most recently captured
437 =head1 CAPTURE FILTER SYNTAX
439 See manual page of tcpdump(8).
441 =head1 DISPLAY FILTER SYNTAX
443 Display filters help you remove the noise from a packet trace and let you see only
444 the packets that interest you. If a packet meets the requirements expressed in your
445 display filter, then it is displayed in the list of packets. Display filters let
446 you compare the fields within a protocol against a specific value, compare fields
447 against fields, and to check the existence of specified fields or protocols.
449 The simplest display filter allows you to check for the existence of a protocol or
450 field. If you want to see all packets which contain the IPX protocol, the filter would be
451 "ipx". (Without the quotation marks) To see all packets that contain a
452 Token-Ring RIF field, use "tr.rif".
454 Fields can also be compared against values. The comparison operators can be expressed
455 either through C-like symbols, or through English-like abbreviations:
461 ge, >= Greater than or Equal to
462 le, <= Less than or Equal to
464 Furthermore, each protocol field is typed. The types are:
466 Unsigned integer (either 8-bit, 16-bit, 24-bit, or 32-bit)
467 Signed integer (either 8-bit, 16-bit, 24-bit, or 32-bit)
469 Ethernet address (6 bytes)
470 Byte string (n-number of bytes)
475 Double-precision floating point number
477 An integer may be expressed in decimal, octal, or hexadecimal notation. The following
478 three display filters are equivalent:
484 Boolean values are either true or false. However, a boolean field is present in a
485 protocol decode only if its value is true. If the value is false, the field is not presence.
486 You can therefore check the truth value of a boolean field by simply checking for its
487 existence, that is, by naming the field. For example, a token-ring packet's source route
488 field is boolean. To find any source-routed packets, the display filter is simply:
492 Non source-routed packets can be found with the negation of that filter:
496 Ethernet addresses, as well as a string of bytes, are represented in hex digits. The hex
497 digits may be separated by colons, periods, or hyphens:
499 fddi.dst eq ff:ff:ff:ff:ff:ff
500 ipx.srcnode == 0.0.0.0.0.1
501 eth.src == aa-aa-aa-aa-aa-aa
503 If a string of bytes contains only one byte, then it is represented as an unsigned integer.
504 That is, if you are testing for hex value 'ff' in a one-byte byte-string, you must compare
505 it agains '0xff' and not 'ff'.
507 IPv4 addresses can be represented in either dotted decimal notation, or by using the hostname:
509 ip.dst eq www.mit.edu
510 ip.src == 192.168.1.1
512 IPv4 address can be compared with the same logical relations as numbers: eq, ne, gt,
513 ge, lt, and le. The IPv4 address is stored in host order, so you do not have to worry
514 about how the endianness of an IPv4 address when using it in a display filter.
516 Classless InterDomain Routing (CIDR) notation can be used to test if an IPv4 address
517 is in a certain subnet. For example, this display filter will find all packets
518 in the 129.111 Class-B network:
520 ip.addr == 129.111.0.0/16
522 Remember, the number after the slash represents the number of bits used to represent
523 the network. CIDR notation can also be used with hostnames, in this example of finding
524 IP addresses on the same Class C network as 'sneezy'
528 The CIDR notation can only be used on IP addresses or hostnames, not in variable names.
529 So, a display filter like "ip.src/24 == ip.dst/24" is not valid. (yet)
531 IPX networks are represented by unsigned 32-bit integers. Most likely you will be using
532 hexadecimal when testing for IPX network values:
534 ipx.srcnet == 0xc0a82c00
536 A substring operator also exists. You can check the substring (byte-string) of any protocol
537 or field. For example, you can filter on the vendor portion of an ethernet address (the first
538 three bytes) like this:
540 eth.src[0:3] == 00:00:83
542 Or more simply, since the number of bytes is inherent in the byte-string you provide, you
543 can provide just the offset. The previous example can be stated like this:
545 eth.src[0] == 00:00:83
547 In fact, the only time you need to explicitly provide a length is when you don't provide
548 a byte-string, and are comparing fields against fields:
550 fddi.src[0:3] == fddi.dst[0:3]
552 If the length of your byte-string is only one byte, then it must be represented in the
553 same way as an unsigned 8-bit integer:
557 You can use the substring operator on a protocol name, too. And remember, the "frame" protocol
558 encompasses the entire packet, allowing you to look at the nth byte of a packet regardless
559 of its frame type (ethernet, token-ring, etc.).
561 token[0:5] ne 0.0.0.1.1
565 Offsets for byte-strings can also be negative, in which case the negative number indicates
566 the number of bytes from the end of the field or protocol that you are testing. Here's how
567 to check the last 4 bytes of a frame:
573 frame[-4:4] == 0.1.2.3
575 All the above tests can be combined together with logical expressions. These too are expressable
576 in C-like syntax or with English-like abbreviations:
583 Expressions can be grouped by parentheses as well. The following are all valid display filter
586 tcp.port == 80 and ip.src == 192.168.2.1
588 (ipx.srcnet == 0xbad && ipx.srnode == 0.0.0.0.0.1) || ip
589 tr.dst[0:3] == 0.6.29 xor tr.src[0:3] == 0.6.29
591 A special caveat must be given regarding fields that occur more than once per packet. "ip.addr"
592 occurs twice per IP packet, once for the source address, and once for the destination address.
593 Likewise, tr.rif.ring fields can occur more than once per packet. The following two expressions
596 ip.addr ne 192.168.4.1
597 not ip.addr eq 192.168.4.1
599 The first filter says "show me all packets where an ip.addr exists that does not equal 192.168.4.1".
600 That is, as long as one ip.addr in the packet does not equal 192.168.44.1, the packet passes
601 the display filter. The second filter "don't show me any packets that have at least one ip.addr
602 field equal to 192.168.4.1". If one ip.addr is 192.168.4.1, the packet does not pass. If B<neither>
603 ip.addr fields is 192.168.4.1, then the packet passes.
605 It is easy to think of the 'ne' and 'eq' operators as having an implict "exists" modifier
606 when dealing with multiply-recurring fields. "ip.addr ne 192.168.4.1" can be thought of as
607 "there exists an ip.addr that does not equal 192.168.4.1".
609 Be careful with multiply-recurring fields; they can be confusing.
611 The following is a table of protocol and protocol fields that are filterable in Ethereal.
612 The abbreviation of the protocol or field is given. This abbreviation is what you use in
613 the display filter. The type of the field is also given.
615 =insert_dfilter_table
619 B</etc/ethers> is consulted to correlate 6-byte hardware addresses to names. If an address is not
620 found in B</etc/ethers>, the B<$HOME/.ethereal/ethers> file is consulted next. Each line
621 contains one hardware address and name, separated by whitespace.
622 The digits of the hardware address are separated by either a colon (:), a dash (-), or
623 a period (.). The following three lines are valid lines of an ethers file:
625 ff:ff:ff:ff:ff:ff Broadcast
626 c0-00-ff-ff-ff-ff TR_broadcast
627 00.00.00.00.00.00 Zero_broadcast
629 B</usr/local/etc/manuf> matches the 3-byte vendor portion of a 6-byte hardware address with
630 the manufacturer's name. The format of the file is the same as the B</etc/ethers> file,
631 except that each address is three bytes instead of six.
633 B</etc/ipxnets> and B<$HOME/.ethereal/ipxnets> correlate 4-byte IPX network numbers to names.
634 The format is the same as the B</etc/ethers> file, except that each address if four bytes
635 instead of six. Additionally, the address can be represented a single hexadecimal number,
636 as is more common in the IPX world, rather than four hex octets. For example, these four
637 lines are valid lines of an ipxnets file.
641 00:00:BE:EF IT_Server1
646 L<tcpdump(8)>, L<pcap(3)>
650 The latest version of B<ethereal> can be found at
651 B<http://ethereal.zing.org>.
657 Gerald Combs <gerald@zing.org>
662 Gilbert Ramirez <gramirez@tivoli.com>
663 Hannes R. Boehm <hannes@boehm.org>
664 Mike Hall <mlh@io.com>
665 Bobo Rajec <bobo@bsp-consulting.sk>
666 Laurent Deniel <deniel@worldnet.fr>
667 Don Lafontaine <lafont02@cn.ca>
668 Guy Harris <guy@alum.mit.edu>
669 Simon Wilkinson <sxw@dcs.ed.ac.uk>
670 Joerg Mayer <jmayer@telemation.de>
671 Martin Maciaszek <fastjack@i-s-o.net>
672 Didier Jorand <Didier.Jorand@alcatel.fr>
673 Jun-ichiro itojun Hagino <itojun@iijlab.net>
674 Richard Sharpe <sharpe@ns.aus.com>
675 John McDermott <jjm@jkintl.com>
676 Jeff Jahr <jjahr@shastanets.com>
677 Brad Robel-Forrest <bradr@watchguard.com>
678 Ashok Narayanan <ashokn@cisco.com>
679 Aaron Hillegass <aaron@classmax.com>
680 Jason Lango <jal@netapp.com>
681 Johan Feyaerts <Johan.Feyaerts@siemens.atea.be>
682 Olivier Abad <abad@daba.dhis.org>
683 Thierry Andry <Thierry.Andry@advalvas.be>
684 Jeff Foster <jjfoste@woodward.com>
685 Peter Torvals <petertv@xoommail.com>
686 Christophe Tronche <ch.tronche@computer.org>
687 Nathan Neulinger <nneul@umr.edu>
688 Tomislav Vujec <tvujec@carnet.hr>
689 Kojak <kojak@bigwig.net>
690 Uwe Girlich <Uwe.Girlich@philosys.de>
691 Warren Young <tangent@mail.com>
692 Heikki Vatiainen <hessu@cs.tut.fi>
694 Alain Magloire <alainm@rcsm.ece.mcgill.ca> was kind enough to give his
695 permission to use his version of snprintf.c.
697 Dan Lasley <dlasley@promus.com> gave permission for his dumpit() hex-dump