Move the definition of MAX_NUM_COLOR_CONVERSATION_COLORS.
[metze/wireshark/wip.git] / README
diff --git a/README b/README
index d1fbb3c36b6810fa177fc464b4340d3be60bdb4a..927a74d2e6d9dd8befb215604e5357267d24bfe8 100644 (file)
--- a/README
+++ b/README
@@ -1,76 +1,83 @@
-$Id: README,v 1.61 2003/09/03 07:11:31 sharpe Exp $
-
 General Information
 ------- -----------
 
-Ethereal is a network traffic analyzer, or "sniffer", for Unix and
+Wireshark 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 Ethereal distribution also comes with Tethereal, which is a
+The Wireshark distribution also comes with TShark, 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
+code as Wireshark, 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.
 
-The official home of Ethereal is
+The official home of Wireshark is
 
-    http://www.ethereal.com
+    http://www.wireshark.org
 
 The latest distribution can be found in the subdirectory
 
-    http://www.ethereal.com/distribution
+    http://www.wireshark.org/download
 
 
 Installation
 ------------
 
-Ethereal is known to compile and run on the following systems:
+Wireshark is known to compile and run on the following systems:
 
-  - Linux (2.0.x, 2.1.x, 2.2.x, 2.3.x, 2.4.x)
-  - Solaris (2.5.1, 2.6, 7)
-  - FreeBSD (2.2.5, 2.2.6, 3.1, 3.2, 3.3)
+  - Linux (2.0 and later kernels, various distributions)
+  - Solaris (2.5.1 and later)
+  - FreeBSD (2.2.5 and later)
+  - NetBSD
+  - OpenBSD
+  - Mac OS X (10.2 and later)
+  - HP-UX (10.20, 11.00, 11.11)
   - Sequent PTX v4.4.5  (Nick Williams <njw@sequent.com>)
-  - Tru64 UNIX (formerly Digital UNIX) (3.2, 4.0)
+  - Tru64 UNIX (formerly Digital UNIX) (3.2 and later)
   - Irix (6.5)
   - AIX (4.3.2, with a bit of work)
-  - Win32 (NT, 98)
+  - Windows (2003, XP, Vista, 7)
+
+and possibly on other versions of those OSes.  It should run on other
+Unix-ish systems without too much trouble.
 
-It should run on other Unix-ish systems without too much trouble.
+If you have an older version of the operating systems listed above, it
+might be supported by an older version of Wireshark. In particular,
+Windows 2000 is supported by Wireshark 1.2.x, Windows NT 4.0 is supported by
+Wireshark 0.99.4, and Windows 95, 98, and ME are supported by Ethereal 0.99.0.
 
 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.
+
+Both Perl and Python are needed, the former for building the man pages.
 
 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'.
 
-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.
-
-You must therefore install Perl, GNU "make", "flex", and either "bison" or
-Berkeley "yacc" on systems that lack them.
+You must therefore install Perl, Python, 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
------          
-
-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.
+-----
+
+In order to capture packets from the network, you need to make the
+dumpcap program set-UID to root, or you need to 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 Wireshark and TShark executables setuid root, or to run them as
+root please don't.  The capture process has been isolated in dumpcap;
+this simple program is less likely to contain security holes, and thus
+safer to run as root.
 
 Please consult the man page for a description of each command-line
 option and interface feature.
@@ -80,83 +87,49 @@ Multiple File Types
 -------------------
 
 The wiretap library is a packet-capture library currently under
-development parallel to ethereal.  In the future it is hoped that
+development parallel to wireshark.  In the future it is hoped that
 wiretap will have more features than libpcap, but wiretap is still in
-its infancy. However, wiretap is used in ethereal for its ability
-to read multiple file types. You can read the following file
-formats:
-
-libpcap (tcpdump -w, etc.) - this is Ethereal's native format
-snoop and atmsnoop
-Shomiti/Finisar Surveyor
-Novell LANalyzer
-Network General/Network Associates DOS-based Sniffer (compressed and
-    uncompressed)
-Microsoft Network Monitor
-AIX's iptrace
-Cinco Networks NetXRray
-Network Associates Windows-based Sniffer
-AG Group/WildPackets EtherPeek/TokenPeek/AiroPeek
-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
-pppd logs (pppdump-format files)
-VMS's TCPIPtrace utility
-DBS Etherwatch for VMS
-Traffic captures from Visual Networks' Visual UpTime
-CoSine L2 debug output
-Output from Accellent's 5Views LAN agents
-
-In addition, it can read gzipped versions of any of these files
+its infancy. However, wiretap is used in wireshark for its ability
+to read multiple file types.  See the Wireshark man page or the
+Wireshark User's Guide for a list of supported file formats.
+
+In addition, it can read gzipped versions of any of those files
 automatically, if you have the zlib library available when compiling
-Ethereal. Ethereal needs a modern version of zlib to be able to use
+Wireshark. Wireshark 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
+prior to 1.0.9 are missing some functions that Wireshark 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.
 
-Although Ethereal can read AIX iptrace files, the documentation on
+Although Wireshark 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
+to the trace file. If a partial packet is saved at the end, Wireshark
 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@ethereal.com, and be sure to send us a copy of that trace
+other packets.  If this occurs, please let the Wireshark developers know
+at wireshark-dev@wireshark.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
+generated by the MAX and Pipline series of products.  Wireshark 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
+commands.
 
-"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"
+Wireshark 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".
 
-CoSine L2 debug output can also be read by Ethereal. To get the L2
+CoSine L2 debug output can also be read by Wireshark. 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 
+To use the Lucent/Ascend, Toshiba and CoSine traces with Wireshark, 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
@@ -174,11 +147,11 @@ Script done on <date/time>
 
 IPv6
 ----
-If your operating system includes IPv6 support, ethereal will attempt to
+If your operating system includes IPv6 support, wireshark 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 to turn off all name resolution (including
+If you want to turn off name resolution while using wireshark, start
+wireshark 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).
@@ -188,73 +161,63 @@ 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
+If you would like to compile wireshark 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
+compile wireshark without IPv6 name resolution, you will still be able to
 decode IPv6 packets, but you'll only see IPv6 addresses, not host names.
 
 
 SNMP
 ----
-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
-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
-ethereal use it, you can run configure with the "--without-ucd-snmp"
+Wireshark can do some basic decoding of SNMP packets; it can also use
+the libsmi library to do more sophisticated decoding, by reading MIB
+files and using the information in those files to display OIDs and
+variable binding values in a friendlier fashion.  The configure script
+will automatically determine whether you have the libsmi library on
+your system.  If you have the libsmi library but _do not_ want to have
+Wireshark use it, you can run configure with the "--without-libsmi"
 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
-"sprint_realloc_objid()" routine; you should either upgrade to version
-4.2.4 or later, as UCD SNMP 4.2.4 fixes some potential buffer overflow
-problems, or should configure with "--without-ucd-snmp".
-
-
 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@ethereal.com.
-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 versions of libraries 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', 'bus error',
+Wireshark is still under constant development, so it is possible that you will
+encounter a bug while using it. Please report bugs at http://bugs.wireshark.org.
+Be sure you enter into the bug:
+
+       1) the complete build information from the "About Wireshark"
+          item in the Help menu or the output of "wireshark -v" for
+          Wireshark bugs and the output of "tshark -v" for TShark bugs;
+
+       2) if the bug happened on Linux, the Linux distribution you were
+          using, and the version of that distribution;
+
+       3) the command you used to invoke Wireshark, if you ran
+          Wireshark from the command line, or TShark, if you ran
+          TShark, 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
+attach to the bug a trace file along with your bug description.  If the
+trace file contains sensitive information (e.g., passwords), then please
+do not send it.
+
+If Wireshark 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
+the wireshark 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 wireshark core
 (gdb) backtrace
 ..... prints the stack trace
 (gdb) quit
 $
 
-The core dump file may be named "ethereal.core" rather than "core" on
+The core dump file may be named "wireshark.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".
+TShark rather than Wireshark, use "tshark" as the first argument to
+the debugger; the core dump may be named "tshark.core".
 
 Disclaimer
 ----------
@@ -263,6 +226,6 @@ There is no warranty, expressed or implied, associated with this product.
 Use at your own risk.
 
 
-Gerald Combs <gerald@ethereal.com>
+Gerald Combs <gerald@wireshark.org>
 Gilbert Ramirez <gram@alumni.rice.edu>
 Guy Harris <guy@alum.mit.edu>