X-Git-Url: http://git.samba.org/samba.git/?a=blobdiff_plain;f=README;h=e01463dbe5e6e73799f63434295a4fde15abf014;hb=3ec08ba7cff9553baaa0e9793ac19ca1c4345538;hp=1f27682e022d2826e3a9b55eaa7074aad6630981;hpb=1c968ed965550f46d09fff7cbc3201972dc6ad8b;p=obnox%2Fwireshark%2Fwip.git diff --git a/README b/README index 1f27682e02..e01463dbe5 100644 --- a/README +++ b/README @@ -1,44 +1,69 @@ +$Id$ + General Information ------- ----------- -Ethereal is a network traffic analyzer 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 +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. - http://ethereal.zing.org +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 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 latest distribution can be found in the subdirectory +The official home of Wireshark is - http://ethereal.zing.org/distribution + http://www.wireshark.org -Interesting and exotic packet traces can be found at +The latest distribution can be found in the subdirectory - http://ethereal.zing.org/~gram/sample.html + 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) - - Solaris (2.5.1, 2.6) - - FreeBSD (2.2.5, 2.2.6) + - 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) + - Windows (2000, 2003, XP, Vista) + +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 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". +Perl is also needed to create the man page. -In addition, ethereal requires "flex" - it cannot be built -with vanilla "lex" - and either "bison" or the Berkeley "yacc". Your flex +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 GNU "make", "flex", and either "bison" or +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. Full installation instructions can be found in the INSTALL file. @@ -49,12 +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 Solaris 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. @@ -64,80 +92,166 @@ 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, Sniffer (uncompresed), NetXray, Sniffer Pro, snoop, -Shomiti, LANalyzer, Network Monitor, iptrace 2.0 (AIX), and +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 - -Although Ethereal can read AIX iptrace files, the documentation on +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 +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 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 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. Wireshark can read +the output of the "wandsession" "wandisplay", "wannext", and "wdd" +commands. + +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 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 +tracefile.out: + +$ script tracefile.out +Script started on +$ telnet router +..... do your trace, then exit from the router's telnet session. +$ exit +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, 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. +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 - 2) Version of GTK+ (the command 'gtk-config --version' will tell you) - 3) The command you used to invoke Ethereal - -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 +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 ---------- @@ -145,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