2003-10-31 08:15:14 +00:00
|
|
|
$Id: README,v 1.62 2003/10/31 08:15:14 guy Exp $
|
2000-02-19 22:01:26 +00:00
|
|
|
|
1998-09-16 02:39:15 +00:00
|
|
|
General Information
|
|
|
|
------- -----------
|
|
|
|
|
1999-08-27 22:57:56 +00:00
|
|
|
Ethereal is a network traffic analyzer, or "sniffer", for Unix and
|
|
|
|
Unix-like operating systems. It uses GTK+, a graphical user interface
|
|
|
|
library, and libpcap, a packet capture and filtering library.
|
1998-09-16 02:39:15 +00:00
|
|
|
|
2000-01-14 08:12:14 +00:00
|
|
|
The Ethereal distribution also comes with Tethereal, which is a
|
|
|
|
line-oriented sniffer (similar to Sun's snoop, or tcpdump) that uses the
|
|
|
|
same dissection, capture-file reading and writing, and packet filtering
|
|
|
|
code as Ethereal, and with editcap, which is a program to read capture
|
|
|
|
files and write the packets from that capture file, possibly in a
|
|
|
|
different capture file format, and with some packets possibly removed
|
|
|
|
from the capture.
|
|
|
|
|
1998-09-16 02:39:15 +00:00
|
|
|
The official home of Ethereal is
|
|
|
|
|
2000-10-08 17:16:29 +00:00
|
|
|
http://www.ethereal.com
|
1998-09-16 02:39:15 +00:00
|
|
|
|
|
|
|
The latest distribution can be found in the subdirectory
|
|
|
|
|
2000-10-08 17:16:29 +00:00
|
|
|
http://www.ethereal.com/distribution
|
1998-09-16 02:39:15 +00:00
|
|
|
|
|
|
|
|
|
|
|
Installation
|
|
|
|
------------
|
|
|
|
|
1998-12-29 03:12:07 +00:00
|
|
|
Ethereal is known to compile and run on the following systems:
|
1998-09-16 02:39:15 +00:00
|
|
|
|
2000-07-28 20:03:59 +00:00
|
|
|
- Linux (2.0.x, 2.1.x, 2.2.x, 2.3.x, 2.4.x)
|
2000-01-14 08:12:14 +00:00
|
|
|
- Solaris (2.5.1, 2.6, 7)
|
|
|
|
- FreeBSD (2.2.5, 2.2.6, 3.1, 3.2, 3.3)
|
1999-04-30 20:31:56 +00:00
|
|
|
- Sequent PTX v4.4.5 (Nick Williams <njw@sequent.com>)
|
1999-04-30 21:16:31 +00:00
|
|
|
- Tru64 UNIX (formerly Digital UNIX) (3.2, 4.0)
|
2000-01-14 08:12:14 +00:00
|
|
|
- Irix (6.5)
|
1999-11-23 03:50:40 +00:00
|
|
|
- AIX (4.3.2, with a bit of work)
|
2000-04-13 11:20:49 +00:00
|
|
|
- Win32 (NT, 98)
|
1998-09-16 02:39:15 +00:00
|
|
|
|
2000-01-26 02:31:35 +00:00
|
|
|
It should run on other Unix-ish systems without too much trouble.
|
1998-09-16 02:39:15 +00:00
|
|
|
|
1999-07-09 04:28:45 +00:00
|
|
|
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".
|
1999-08-27 22:57:56 +00:00
|
|
|
Perl is also needed to create the man page.
|
1999-07-09 04:28:45 +00:00
|
|
|
|
1999-08-27 22:57:56 +00:00
|
|
|
If you decide to modify the yacc grammar or lex scanner, then
|
|
|
|
you need "flex" - it cannot be built with vanilla "lex" -
|
|
|
|
and either "bison" or the Berkeley "yacc". Your flex
|
1999-08-03 16:33:12 +00:00
|
|
|
version must be 2.5.1 or greater. Check this with 'flex -V'.
|
1999-07-09 04:28:45 +00:00
|
|
|
|
2000-07-28 20:03:59 +00:00
|
|
|
If you decide to modify the NetWare Core Protocol dissector, you
|
|
|
|
will need python, as the data for packet types is stored in a python
|
|
|
|
script, ncp2222.py.
|
|
|
|
|
1999-08-27 22:57:56 +00:00
|
|
|
You must therefore install Perl, GNU "make", "flex", and either "bison" or
|
1999-07-09 04:28:45 +00:00
|
|
|
Berkeley "yacc" on systems that lack them.
|
1998-09-16 02:39:15 +00:00
|
|
|
|
1998-12-29 03:12:07 +00:00
|
|
|
Full installation instructions can be found in the INSTALL file.
|
1998-09-16 02:39:15 +00:00
|
|
|
|
1999-04-30 21:16:31 +00:00
|
|
|
See also the appropriate README.<OS> files for OS-specific installation
|
|
|
|
instructions.
|
1998-12-29 03:12:07 +00:00
|
|
|
|
1998-09-16 02:39:15 +00:00
|
|
|
Usage
|
|
|
|
-----
|
|
|
|
|
2000-01-14 08:12:14 +00:00
|
|
|
In order to capture packets from the network, you need to be running as
|
|
|
|
root, or have access to the appropriate entry under /dev if your system
|
|
|
|
is so inclined (BSD-derived systems, and systems such as Solaris and
|
|
|
|
HP-UX that support DLPI, typically fall into this category). Although
|
|
|
|
it might be tempting to make the Ethereal executable setuid root, please
|
|
|
|
don't - alpha code is by nature not very robust, and liable to contain
|
|
|
|
security holes.
|
1998-12-29 03:12:07 +00:00
|
|
|
|
|
|
|
Please consult the man page for a description of each command-line
|
|
|
|
option and interface feature.
|
1998-09-16 02:39:15 +00:00
|
|
|
|
|
|
|
|
1998-11-12 06:01:27 +00:00
|
|
|
Multiple File Types
|
|
|
|
-------------------
|
|
|
|
|
1998-11-18 20:10:30 +00:00
|
|
|
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
|
1999-07-09 04:18:36 +00:00
|
|
|
its infancy. However, wiretap is used in ethereal for its ability
|
1999-07-09 04:28:45 +00:00
|
|
|
to read multiple file types. You can read the following file
|
2000-08-22 06:50:16 +00:00
|
|
|
formats:
|
|
|
|
|
2001-12-05 20:01:03 +00:00
|
|
|
libpcap (tcpdump -w, etc.) - this is Ethereal's native format
|
2002-01-22 22:38:05 +00:00
|
|
|
snoop and atmsnoop
|
|
|
|
Shomiti/Finisar Surveyor
|
|
|
|
Novell LANalyzer
|
|
|
|
Network General/Network Associates DOS-based Sniffer (compressed and
|
|
|
|
uncompressed)
|
2000-08-22 06:50:16 +00:00
|
|
|
Microsoft Network Monitor
|
|
|
|
AIX's iptrace
|
2002-01-22 22:38:05 +00:00
|
|
|
Cinco Networks NetXRray
|
|
|
|
Network Associates Windows-based Sniffer
|
2002-01-29 09:45:58 +00:00
|
|
|
AG Group/WildPackets EtherPeek/TokenPeek/AiroPeek
|
2000-08-22 06:50:16 +00:00
|
|
|
RADCOM's WAN/LAN Analyzer
|
|
|
|
Lucent/Ascend access products
|
|
|
|
HP-UX's nettl
|
|
|
|
Toshiba's ISDN routers
|
|
|
|
ISDN4BSD "i4btrace" utility
|
|
|
|
Cisco Secure Intrustion Detection System iplogging facility
|
2000-09-20 12:09:52 +00:00
|
|
|
pppd logs (pppdump-format files)
|
2001-12-04 22:43:41 +00:00
|
|
|
VMS's TCPIPtrace utility
|
|
|
|
DBS Etherwatch for VMS
|
2001-12-05 21:42:07 +00:00
|
|
|
Traffic captures from Visual Networks' Visual UpTime
|
2002-07-31 19:27:57 +00:00
|
|
|
CoSine L2 debug output
|
2003-07-29 19:42:01 +00:00
|
|
|
Output from Accellent's 5Views LAN agents
|
2003-10-31 08:15:14 +00:00
|
|
|
Endace Measurement Systems' ERF format
|
|
|
|
Linux Bluez Bluetooth stack "hcidump -w" traces
|
|
|
|
Network Instruments Observer version 9
|
1999-03-28 18:32:03 +00:00
|
|
|
|
2000-06-08 03:09:32 +00:00
|
|
|
In addition, it can read gzipped versions of any of these files
|
1999-11-29 02:40:15 +00:00
|
|
|
automatically, if you have the zlib library available when compiling
|
1999-11-29 05:10:18 +00:00
|
|
|
Ethereal. Ethereal needs a modern version of zlib to be able to use
|
|
|
|
zlib to read gzipped files; version 1.1.3 is known to work. Versions
|
|
|
|
prior to 1.0.9 are missing some functions that Ethereal needs and won't
|
|
|
|
work. "./configure" should detect if you have the proper zlib version
|
|
|
|
available and, if you don't, should disable zlib support. You can always
|
|
|
|
use "./configure --disable-zlib" to explicitly disable zlib support.
|
1999-11-29 02:40:15 +00:00
|
|
|
|
1999-08-20 04:07:09 +00:00
|
|
|
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
|
2001-01-10 06:23:58 +00:00
|
|
|
at ethereal-dev@ethereal.com, and be sure to send us a copy of that trace
|
1999-08-20 04:07:09 +00:00
|
|
|
file if it's small and contains non-sensitive data.
|
|
|
|
|
1999-09-13 03:51:09 +00:00
|
|
|
Support for Lucent/Ascend products is limited to the debug trace output
|
|
|
|
generated by the MAX and Pipline series of products. Ethereal can read
|
|
|
|
the output of the "wandsession" "wandisplay", "wannext", and "wdd"
|
|
|
|
commands. For detailed information on use of these commands, please refer
|
|
|
|
the following pages:
|
|
|
|
|
|
|
|
"wandsession", "wandisplay", and "wannext" on the Pipeline series:
|
|
|
|
http://aos.ascend.com/aos:/gennavviewer.html?doc_id=0900253d80006c79
|
|
|
|
|
|
|
|
"wandsession", "wandisplay", and "wannext" on the MAX series:
|
|
|
|
http://aos.ascend.com/aos:/gennavviewer.html?doc_id=0900253d80006972
|
|
|
|
|
|
|
|
"wdd" on the Pipeline series:
|
|
|
|
http://aos.ascend.com/aos:/gennavviewer.html?doc_id=0900253d80006877
|
|
|
|
|
1999-10-31 17:46:11 +00:00
|
|
|
Ethereal can also read dump trace output from the Toshiba "Compact Router"
|
|
|
|
line of ISDN routers (TR-600 and TR-650). You can telnet to the router
|
|
|
|
and start a dump session with "snoop dump".
|
|
|
|
|
2002-07-31 19:27:57 +00:00
|
|
|
CoSine L2 debug output can also be read by Ethereal. To get the L2
|
|
|
|
debug output, get in the diags mode first and then use
|
|
|
|
"create-pkt-log-profile" and "apply-pkt-log-profile" commands under
|
|
|
|
layer-2 category. For more detail how to use these commands, you
|
|
|
|
should examine the help command by "layer-2 create ?" or "layer-2 apply ?".
|
|
|
|
|
|
|
|
To use the Lucent/Ascend, Toshiba and CoSine traces with Ethereal, you must
|
|
|
|
capture the trace output to a file on disk. The trace is happening inside
|
|
|
|
the router and the router has no way of saving the trace to a file for you.
|
1999-10-31 17:46:11 +00:00
|
|
|
An easy way of doing this under Unix is to run "telnet <ascend> | tee <outfile>".
|
|
|
|
Or, if your system has the "script" command installed, you can save
|
|
|
|
a shell session, including telnet to a file. For example, to a file named
|
|
|
|
tracefile.out:
|
|
|
|
|
|
|
|
$ script tracefile.out
|
|
|
|
Script started on <date/time>
|
|
|
|
$ telnet router
|
|
|
|
..... do your trace, then exit from the router's telnet session.
|
|
|
|
$ exit
|
|
|
|
Script done on <date/time>
|
|
|
|
|
1999-09-13 03:51:09 +00:00
|
|
|
|
1999-03-28 18:32:03 +00:00
|
|
|
|
|
|
|
IPv6
|
|
|
|
----
|
|
|
|
If your operating system includes IPv6 support, ethereal will attempt to
|
2002-05-29 19:16:40 +00:00
|
|
|
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 to turn off all name resolution (including
|
|
|
|
resolution of MAC addresses and TCP/UDP/SMTP port numbers to names), or
|
|
|
|
with the "-N mt" option to turn off name resolution for all
|
|
|
|
network-layer addresses (IPv4, IPv6, IPX).
|
|
|
|
|
|
|
|
You can make that the default setting by opening the Preferences dialog
|
|
|
|
box using the Preferences item in the Edit menu, selecting "Name
|
|
|
|
resolution", turning off the appropriate name resolution options,
|
|
|
|
clicking "Save", and clicking "OK".
|
|
|
|
|
|
|
|
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.
|
1999-03-28 18:32:03 +00:00
|
|
|
|
1998-11-12 06:01:27 +00:00
|
|
|
|
1999-06-21 16:02:22 +00:00
|
|
|
SNMP
|
|
|
|
----
|
2002-03-11 02:12:41 +00:00
|
|
|
Ethereal can do some basic decoding of SNMP packets; it can also use the
|
|
|
|
UCD SNMP library, version 4.2.2 or later, to do more sophisticated
|
|
|
|
decoding, by reading MIB files and using the information in those files
|
2002-05-20 19:13:20 +00:00
|
|
|
to display OIDs and variable binding values in a friendlier fashion.
|
|
|
|
The configure script will automatically determine whether you have the
|
|
|
|
UCD SNMP library on your system, and will use it if it's version 4.2.2
|
|
|
|
or later. If you have an SNMP library but _do not_ want to have
|
2003-09-03 07:11:31 +00:00
|
|
|
ethereal use it, you can run configure with the "--without-ucd-snmp"
|
2002-05-20 19:13:20 +00:00
|
|
|
option.
|
|
|
|
|
|
|
|
If you have an earlier version of the UCD SNMP library on your system,
|
|
|
|
the configure script will stop, reporting that it can't find the
|
2002-03-11 02:12:41 +00:00
|
|
|
"sprint_realloc_objid()" routine; you should either upgrade to version
|
2002-05-20 19:13:20 +00:00
|
|
|
4.2.4 or later, as UCD SNMP 4.2.4 fixes some potential buffer overflow
|
2003-09-03 07:11:31 +00:00
|
|
|
problems, or should configure with "--without-ucd-snmp".
|
1999-06-21 16:02:22 +00:00
|
|
|
|
1999-08-27 22:57:56 +00:00
|
|
|
|
1999-08-20 04:07:09 +00:00
|
|
|
How to Report a Bug
|
|
|
|
-------------------
|
|
|
|
Ethereal is still under constant development, so it is possible that you will
|
2001-01-10 06:23:58 +00:00
|
|
|
encounter a bug while using it. Please report bugs to ethereal-dev@ethereal.com.
|
1999-08-20 04:07:09 +00:00
|
|
|
Be sure you tell us:
|
|
|
|
|
1999-11-04 19:14:53 +00:00
|
|
|
1) Operating System and version (the command 'uname -sr' may
|
|
|
|
tell you this, although on Linux systems it will probably
|
|
|
|
tell you only the version number of the Linux kernel, not of
|
|
|
|
the distribution as a whole; on Linux systems, please tell us
|
|
|
|
both the version number of the kernel, and which version of
|
|
|
|
which distribution you're running)
|
1999-08-20 04:07:09 +00:00
|
|
|
2) Version of GTK+ (the command 'gtk-config --version' will tell you)
|
1999-11-04 19:14:53 +00:00
|
|
|
3) Version of Ethereal (the command 'ethereal -v' will tell you,
|
1999-11-04 21:18:50 +00:00
|
|
|
unless the bug is so severe as to prevent that from working,
|
1999-11-29 04:38:23 +00:00
|
|
|
and should also tell you the versions of libraries with which
|
|
|
|
it was built)
|
1999-11-04 19:14:53 +00:00
|
|
|
4) The command you used to invoke Ethereal, and the sequence of
|
|
|
|
operations you performed that caused the bug to appear
|
1999-08-20 04:07:09 +00:00
|
|
|
|
|
|
|
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
|
1999-11-04 19:14:53 +00:00
|
|
|
greater than 1 MB when compressed. If the trace file contains sensitive
|
1999-08-20 04:07:09 +00:00
|
|
|
information (e.g., passwords), then please do not send it.
|
|
|
|
|
2000-08-24 23:33:09 +00:00
|
|
|
If Ethereal died on you with a 'segmentation violation', 'bus error',
|
|
|
|
'abort', or other error that produces a UNIX core dump file, you can
|
|
|
|
help the developers a lot if you have a debugger installed. A stack
|
|
|
|
trace can be obtained by using your debugger ('gdb' in this example),
|
|
|
|
the ethereal binary, and the resulting core file. Here's an example of
|
|
|
|
how to use the gdb command 'backtrace' to do so.
|
1999-08-20 04:07:09 +00:00
|
|
|
|
|
|
|
$ gdb ethereal core
|
1999-08-20 06:01:07 +00:00
|
|
|
(gdb) backtrace
|
1999-08-20 04:07:09 +00:00
|
|
|
..... prints the stack trace
|
1999-08-20 06:01:07 +00:00
|
|
|
(gdb) quit
|
|
|
|
$
|
1999-06-21 16:02:22 +00:00
|
|
|
|
2000-08-24 23:33:09 +00:00
|
|
|
The core dump file may be named "ethereal.core" rather than "core" on
|
|
|
|
some platforms (e.g., BSD systems). If you got a core dump with
|
|
|
|
Tethereal rather than Ethereal, use "tethereal" as the first argument to
|
|
|
|
the debugger; the core dump may be named "tethereal.core".
|
|
|
|
|
1998-09-16 02:39:15 +00:00
|
|
|
Disclaimer
|
|
|
|
----------
|
|
|
|
|
|
|
|
There is no warranty, expressed or implied, associated with this product.
|
|
|
|
Use at your own risk.
|
1999-04-30 20:31:56 +00:00
|
|
|
|
|
|
|
|
2001-01-10 10:11:27 +00:00
|
|
|
Gerald Combs <gerald@ethereal.com>
|
2001-11-13 23:55:44 +00:00
|
|
|
Gilbert Ramirez <gram@alumni.rice.edu>
|
2000-07-28 20:03:59 +00:00
|
|
|
Guy Harris <guy@alum.mit.edu>
|