Update documentation about iptrace version support.
[metze/wireshark/wip.git] / README
diff --git a/README b/README
index 8f9296d5239aac6ccb685082069d042ec05ce16a..d40e4efc74a522b076bbd992a7d26f7efe612c5c 100644 (file)
--- a/README
+++ b/README
@@ -1,9 +1,9 @@
 General Information
 ------- -----------
 
-Ethereal is a network traffic analyzer for Unix and Unix-like operating
-systems.  It is based on GTK+, a graphical user interface library,
-and libpcap, a packet capture and filtering library.
+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.
 
 The official home of Ethereal is
 
@@ -28,9 +28,22 @@ Ethereal is known to compile and run on the following systems:
   - 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)
+  - Irix (version?)
+  - AIX (4.3.2, with a bit of work)
 
 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".
+Perl is also needed to create the man page.
+
+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
+version must be 2.5.1 or greater. Check this with 'flex -V'.
+
+You must therefore install Perl, GNU "make", "flex", and either "bison" or
+Berkeley "yacc" on systems that lack them.
 
 Full installation instructions can be found in the INSTALL file.
          
@@ -57,22 +70,60 @@ Multiple File Types
 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
-libpcap, Sniffer, NetXray (and Sniffer Pro), Sun "snoop", LANalyzer,
-Microsoft Network Monitor, and AIX "iptrace" 2.0 trace files. Some minimal
-display filters now work. But because "Follow TCP Stream" relies on IP and TCP
-display filtering, and those aren't yet available in wiretap's display filter
-system, "Follow TCP Stream" is turned off when you compile --with-wiretap.
-
-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 (tcpdump -w), Sniffer (uncompressed), NetXray, Sniffer Pro,
+snoop, Shomiti, LANalyzer, Network Monitor, AIX's iptrace,
+RADCOM's WAN/LAN Analyzer, Lucent/Ascend access products, HP-UX's nettl,
+and Toshiba's ISDN routers.
+
+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.
+
+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
+
+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".
+
+To use the Lucent/Ascend and Toshiba 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.
+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>
 
-If you want to add support for other packet-capture file formats, please
-look at the wiretap source code in the wiretap directory.
-
-Please report any problems that are wiretap related to
-Gilbert Ramirez <gram@verdict.uthscsa.edu>.
 
 
 IPv6
@@ -101,6 +152,44 @@ 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:
+
+       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)
+       2) Version of GTK+ (the command 'gtk-config --version' will tell you)
+       3) Version of Ethereal (the command 'ethereal -v' will tell you,
+          unless the bug is so severe as to prevent that from working,
+          and should also tell you the version of GTK+ and, if built
+          with "libpcap", the version of "libpcap" with which it was
+          built)
+       4) The command you used to invoke Ethereal, and the sequence of
+          operations you performed that caused the bug to appear
+
+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
+greater than 1 MB 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 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.
+
+$ gdb ethereal core
+(gdb) backtrace
+..... prints the stack trace
+(gdb) quit
+$
+
 Disclaimer
 ----------
 
@@ -109,4 +198,4 @@ Use at your own risk.
 
 
 Gerald Combs <gerald@zing.org>
-Gilbert Ramirez <gram@verdict.uthscsa.edu>
+Gilbert Ramirez <gram@xiexie.org>