------- -----------
Ethereal is a network traffic analyzer for Unix and Unix-like operating
-systems. It is based on GTK+, a graphical user interface library,
+systems. It uses GTK+, a graphical user interface library,
and libpcap, a packet capture and filtering library.
The official home of Ethereal is
http://ethereal.zing.org/distribution
+Interesting and exotic packet traces can be found at
+
+ http://ethereal.zing.org/~gram/sample.html
+
Installation
------------
Ethereal is known to compile and run on the following systems:
- - Linux (2.0.x)
+ - Linux (2.0.x, 2.1.x, 2.2.x)
- Solaris (2.5.1, 2.6)
- FreeBSD (2.2.5, 2.2.6)
+ - Sequent PTX v4.4.5 (Nick Williams <njw@sequent.com>)
+ - Tru64 UNIX (formerly Digital UNIX) (3.2, 4.0)
It should run on other systems without too much trouble.
+NOTE: the Makefile appears to depend on GNU "make"; it doesn't appear to
+work with the "make" that comes with Solaris 7 nor the BSD "make".
+
+In addition, ethereal requires "flex" - it cannot be built
+with vanilla "lex" - and either "bison" or the Berkeley "yacc". Your flex
+version must be 2.5.1 or greater. Check this with 'flex -V'.
+
+You must therefore install GNU "make", "flex", and either "bison" or
+Berkeley "yacc" on systems that lack them.
Full installation instructions can be found in the INSTALL file.
+See also the appropriate README.<OS> files for OS-specific installation
+instructions.
Usage
-----
The wiretap library is a packet-capture library currently under
development parallel to ethereal. In the future it is hoped that
wiretap will have more features than libpcap, but wiretap is still in
-its infancy. You can compile ethereal with the wiretap library by using
-'./configure --with-wiretap'. Using wiretap will allow you to read
-pcap, Sniffer, Sun "snoop", LANalyzer, Microsoft Network Monitor, and
-AIX "iptrace" 2.0 trace files, but it disables display filters. You can
-still capture packets from within ethereal using libpcap, and therefore
-use libpcap-style capture filters, however.
+its infancy. However, wiretap is used in ethereal for its ability
+to read multiple file types. You can read the following file
+formats, and create display filters for them as well:
+
+libpcap, Sniffer (uncompresed), NetXray, Sniffer Pro, snoop,
+Shomiti, LANalyzer, Network Monitor, iptrace 2.0 (AIX), and
+RADCOM's WAN/LAN Analyzer
+
+Although Ethereal can read AIX iptrace files, the documentation on
+AIX's iptrace packet-trace command is sparse. The 'iptrace' command
+starts a daemon which you must kill in order to stop the trace. Through
+experimentation it appears that sending a HUP signal to that iptrace
+daemon causes a graceful shutdown and a complete packet is written
+to the trace file. If a partial packet is saved at the end, Ethereal
+will complain when reading that file, but you will be able to read all
+other packets. If this occurs, please let the Ethereal developers know
+at ethereal-dev@zing.org, and be sure to send us a copy of that trace
+file if it's small and contains non-sensitive data.
+
+
+IPv6
+----
+If your operating system includes IPv6 support, ethereal will attempt to
+use reverse name resolution capabilities when decoding IPv6 packets. If
+you want to turn off name resolution while using ethereal, start ethereal
+with the "-n" option. If you would like to compile ethereal without
+support for IPv6 name resolution, use the "--disable-ipv6" option with
+"./configure". If you compile ethereal without IPv6 name resolution,
+you will still be able to decode IPv6 packets, but you'll only see IPv6
+addresses, not host names.
+
+The "Follow TCP Stream" feature only supports TCP over IPv4. Support for TCP
+over IPv6 is planned.
+
+
+SNMP
+----
+Ethereal can do some basic decoding of SNMP packets, but it relies on an
+external SNMP library to do this. You can use either the UCD or the CMU
+SNMP libraries. The configure script will automatically determine which
+library you have on your system and will use it. If you have an SNMP
+library but _do not_ want to have ethereal use it, you can run configure
+with the "--disable-snmp" option. No SNMP support will be compiled into
+ethereal with this option.
+
+How to Report a Bug
+-------------------
+Ethereal is still under constant development, so it is possible that you will
+encounter a bug while using it. Please report bugs to ethereal-dev@zing.org.
+Be sure you tell us:
-If you can live without display filters and would like to read non-pcap
-capture files, give wiretap a try. If you want to add support for other
-packet-capture file formats, please look at the wiretap source code in the
-wiretap directory.
+ 1) Operating System and version
+ 2) Version of GTK+ (the command 'gtk-config --version' will tell you)
+ 3) The command you used to invoke Ethereal
-Please report any problems that are wiretap related to
-Gilbert Ramirez <gram@verdict.uthscsa.edu>. He uses token-ring at work, so he
-is especially interested in any non-token-ring trace files you can send him.
+If the bug is produced by a particular trace file, please be sure to send
+a trace file along with your bug description. Please don't send a trace file
+greather than 1MB when compressed. If the trace file contains sensitive
+information (e.g., passwords), then please do not send it.
+
+If Ethereal died on you with a 'segmentation violation', you can help the
+developers a lot if you have your debugger installed. A stack trace using
+your debugger ('gdb' in this example), the ethereal binary, and the
+resulting core file can be obtained by starting the debugger and using
+the 'backtrace' command.
+
+$ gdb ethereal core
+> backtrace
+..... prints the stack trace
+> quit
Disclaimer
There is no warranty, expressed or implied, associated with this product.
Use at your own risk.
+
+
+Gerald Combs <gerald@zing.org>
+Gilbert Ramirez <gram@verdict.uthscsa.edu>