X-Git-Url: http://git.samba.org/?a=blobdiff_plain;f=README;h=2919a88a607e88f73a85e87e45c54cd5ec5f8bc7;hb=9e36106bafc4919a46ea7ae27c43d98815dfe9c9;hp=6dec8976ebb7f2e8c83b0417afee56b96c594d3a;hpb=1ffac9e682afc0fb0f4a61fb70a2353b58da6861;p=metze%2Fwireshark%2Fwip.git diff --git a/README b/README index 6dec8976eb..2919a88a60 100644 --- a/README +++ b/README @@ -1,63 +1,85 @@ General Information -------- ----------- +------------------- -Ethereal is a network traffic analyzer, or "sniffer", for Unix and -Unix-like operating systems. It uses GTK+, a graphical user interface +Wireshark is a network traffic analyzer, or "sniffer", for Unix and +Unix-like operating systems. It uses Qt, a graphical user interface library, and libpcap, a packet capture and filtering library. -The official home of Ethereal is - - 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 + https://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 + https://www.wireshark.org/download Installation ------------ -Ethereal is known to compile and run on the following systems: +The Wireshark project builds and tests regularly on the following platforms: + + - Linux (Ubuntu) + - Microsoft Windows + - macOS / {Mac} OS X - - Linux (2.0.x, 2.1.x, 2.2.x) - - Solaris (2.5.1, 2.6) - - FreeBSD (2.2.5, 2.2.6) - - Sequent PTX v4.4.5 (Nick Williams ) - - Tru64 UNIX (formerly Digital UNIX) (3.2, 4.0) - - Irix (version?) +Official installation packages are available for Microsoft Windows and +macOS. -It should run on other systems without too much trouble. +It is available as either a standard or add-on package for many popular +operating sytems and Linux distributions including Debian, Ubuntu, Fedora, +CentOS, RHEL, Arch, Gentoo, openSUSE, FreeBSD, DragonFly BSD, NetBSD, and +OpenBSD. -NOTE: the Makefile appears to depend on GNU "make"; it doesn't appear to +Additionaly it is available through many third-party packaging systems +such as pkgsrc, OpenCSW, Homebrew, and MacPorts. + +It should run on other Unix-ish systems without too much trouble. + +In some cases the current version of Wireshark might not support your +operating system. This is the case for Windows XP, which is supported by +Wireshark 1.10 and earlier. In other cases the standard package for +Wireshark might simply be old. This is the case for Solaris and HP-UX. + +NOTE: The Makefile depends 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'. -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 and in the +Developer's Guide at https://www.wireshark.org/docs/wsdg_html_chunked/ -Full installation instructions can be found in the INSTALL file. - See also the appropriate README. 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 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. @@ -67,124 +89,138 @@ 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, and create display filters for them as well: - -libpcap (tcpdump -w), Sniffer (uncompressed), NetXray, Sniffer Pro, -snoop, Shomiti, LANalyzer, Network Monitor, AIX's iptrace 2.0, -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 +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 +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. 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: +commands. -"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" +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 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 +---- +Name Resolution +--------------- -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. +Wireshark will attempt to use reverse name resolution capabilities +when decoding IPv4 and 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". 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 (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) - 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 under constant development, so it is possible that you will +encounter a bug while using it. Please report bugs at https://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 ---------- @@ -193,5 +229,8 @@ 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