X-Git-Url: http://git.samba.org/samba.git/?p=obnox%2Fwireshark%2Fwip.git;a=blobdiff_plain;f=README;h=e01463dbe5e6e73799f63434295a4fde15abf014;hp=62886214f4dfb026757fded2607010057bec95b1;hb=056fd16bc7c072236118c62f997ad90d9af03098;hpb=b19aac36fe78d15e26cdc1b862b2f06f14675e56 diff --git a/README b/README index 62886214f4..e01463dbe5 100644 --- a/README +++ b/README @@ -1,44 +1,54 @@ -$Id: README,v 1.36 2000/02/19 22:01:26 guy Exp $ +$Id$ 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://ethereal.zing.org + http://www.wireshark.org The latest distribution can be found in the subdirectory - http://ethereal.zing.org/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) - - 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 ) - - 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; read-only, no capturing yet) + - Windows (2000, 2003, XP, Vista) -It should run on other Unix-ish systems without too much trouble. +and possibly on other versions of those OSes. 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 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". @@ -49,6 +59,10 @@ 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. @@ -60,13 +74,15 @@ 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. @@ -76,59 +92,78 @@ 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 +its infancy. However, wiretap is used in wireshark 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, Microsoft Network Monitor, AIX's iptrace, -RADCOM's WAN/LAN Analyzer, Lucent/Ascend access products, HP-UX's nettl, -Toshiba's ISDN routers, and the ISDN4BSD "i4btrace" utility. - -In addition, it can read gzipped versions of any of these files, +formats: + +libpcap (tcpdump -w, etc.) - this is Wireshark'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/EtherHelp +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 +Endace Measurement Systems' ERF format +Linux Bluez Bluetooth stack "hcidump -w" traces +Network Instruments Observer version 9 +Trace files for the EyeSDN USB S0 + +In addition, it can read gzipped versions of any of these 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@zing.org, 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". -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. +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 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 | tee ". 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 @@ -145,66 +180,78 @@ Script done on 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. +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 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). -The "Follow TCP Stream" feature only supports TCP over IPv4. Support for TCP -over IPv6 is planned. +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 wireshark without support for IPv6 name +resolution, use the "--disable-ipv6" option with "./configure". If you +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 an -external SNMP library to do more sophisticated decoding.. 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. - +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. 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 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', 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 +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 wireshark binary, and the resulting core file. Here's an example of +how to use the gdb command 'backtrace' to do so. + +$ gdb wireshark core (gdb) backtrace ..... prints the stack trace (gdb) quit $ +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 +TShark rather than Wireshark, use "tshark" as the first argument to +the debugger; the core dump may be named "tshark.core". + Disclaimer ---------- @@ -212,5 +259,6 @@ There is no warranty, expressed or implied, associated with this product. Use at your own risk. -Gerald Combs -Gilbert Ramirez +Gerald Combs +Gilbert Ramirez +Guy Harris