*** README DOCUMENT FOR IPTRAF 1.4 *** DESCRIPTION IPTraf is a console-based network monitoring program for Linux that displays information about IP traffic. It returns such information as: Current TCP connections UDP, ICMP, OSPF, and other types of IP packets Packet and byte counts on TCP connections IP, TCP, UDP, ICMP, non-IP, and other packet and byte counts TCP/UDP counts by ports Interface activity Flag statuses on TCP packets LAN station statistics This program can be used to determine the type of traffic on your network, and what kind of service is the most heavily used on what machines, among others. IPTraf works on Ethernet, FDDI, ISDN, PLIP, and SLIP/PPP interfaces. The IPTraf Web page is at http://cebu.mozcom.com/riker/iptraf DISTRIBUTION NOTICE This is the general release of IPTraf. IPTraf has been incorporated into the Debian GNU/Linux and S.u.S.E. distributions, as well as the Trinux security toolkit distribution. Linux distributions may have tailored the IPTraf package to suit their purposes. Direct questions, comments or inquiries about a distribution-specific package to its maintainer. NEW FEATURES IN VERSION 1.4 Additional ISDN Support IPTraf now supports raw IP and Cisco HDLC encapsulation over ISDN lines. Synchronous PPP over ISDN has been in place since version 1.3. Reorganized IP Traffic Monitor Log Entries IP traffic monitor log entries now have a more consistent format for easier processing with scripts. NEW FEATURES IN VERSION 1.3 Screen Update Speed Control An additional option to control the screen update interval. This allows you to control IPTraf's traffic generation on remote terminals and slow links. Better Organized Menus The selection menus have been modified with separator lines to better sight logically-related items. FDDI Support FDDI is now supported. (FDDI is still undergoing observation. Keep an eye out on it, and report any problems.) ISDN Reenabled With incoming reports that the packet parsing errors are gone with kernel 2.0.35, synchronous PPP over ISDN interfaces have been reenabled. Better Numeric Overflow Protection IPTraf now begins to display numbers in K(ilo), M(ega), G(iga) and T(era) notation as they grow on long-term monitors. Storage space for rapidly-increasing counts have also been doubled. Internal Hash Table for IP Traffic Monitor A hash table has been incorporated into the IP Traffic Monitor for better search times. NEW FEATURES IN VERSION 1.2 Literal TCP/UDP Service Identifiers Starting with version 1.2, IPTraf can now display (at the user's option) TCP and UDP service identifiers in both literal (service name, e.g. telnet) and numeric (port number, e.g. 23) forms. The display form can be set at the Options menu and will affect both the IP traffic monitor and TCP/UDP services monitor. Ethernet Address Mappings The make the LAN station monitor a bit clearer, version 1.2.0 now includes a facility that allows you to attach descriptions for various Ethernet addresses. This facility can be accessed from the Ethernet host descriptions main menu item. See the manual for more details. Inverse Filter Logic TCP and UDP filters now contain an extra field that allows users to selectively include or exclude sites from the display. This is good if you want to display "all data except from/to etc., etc." See the manual for more details. TCP/UDP Filter Autosave TCP and UDP filters now stay in effect even after the program exits. They take effect immediately on the next restart. NEW FEATURES IN VERSION 1.1 Command-line Interface Options are now available at the command line that allow you to immediately start a facility, rather than start from the main menu. See the manual or issue iptraf with the -h parameter to display a help screen. Improved Interface Lists and Access The general interface statistics screen will now grow as packets are detected on new interfaces (such as new PPP interfaces). In addition to this, long interface lists can now be scrolled in both the selection boxes and the general interface statistics window. The rvnamed Daemon IPTraf 1.1 now comes with rvnamed, a daemon that resolves IP addresses into host names in the background, while allowing IPTraf to continue in the meantime. This minimizes the blocking action of gethostbyaddr(), allowing better keyboard control and less lost packets due to the delay caused by reverse name lookup on the Internet. When an IP address is submitted for resolution into a host name, IPTraf passes it to rvnamed which forks off and performs the resolution in the background. In the meantime, an IP address will be returned. Subsequent requests will cause rvnamed to look up its internal table for already-resolved IP addresses and return those to IPTraf once they're found. GLIBC2 (LIBC6) SUPPORT I've done some rather extensive modifications to the code to get it to compile with glibc2. It's probably somewhat dirty now, but it's going to get cleaned up. Right now, I have to get the package to compile with both libc5 and libc6, and to do that, I had to include a few files normally part of the library right in the distribution directory included as local headers, and a custom definition of the TCP header in tcphdr.h. libc6 will most likely overtake and eventually replace libc5 as the standard as distributions are moving in that direction (much like ELF took over the a.out format a few years ago). However, I will continue to distribute the precompiled binaries for libc5, that being the least common denominator. DOCUMENTATION The manual is found in the Documentation subdirectory and is now available in HTML and plain text. The HTML version can be viewed with any browser supporting HTML 3.2. The HTML version is also online on the World Wide Web at http://cebu.mozcom.com/riker/iptraf/manual.html For information on the fixes and other changes made to IPTraf, see the included CHANGES file. For a detailed description of the new rvnamed program, see the README.rvnamed file. TECHNICAL NOTES Program Security IPTraf reads in raw network packets by using the raw socket interface to the kernel. As such, it must be run as root. This program was written for use by administrators. While effort has been exerted to avoid buffer overruns, no guarantee is still given, as this is not intended for ordinary users. Setting the setuid bit is NOT recommended. Doing so may pose a security risk to your system. Do so only if you are the only user on your system. (If the program is not compiled with the ALLOWUSERS tag defined in the Makefile, only the root user will be able to run the program, even if its setuid bit is on. If you want to override this and allow setuid operation, you will have to include the -DALLOWSERS option in the Makefile and recompile. The distribution executable program comes compiled to disallow non-root users from using the program.) In short, this program is not declared safe for non-root users to use. (The new rvnamed reverse lookup daemon runs in the background and uses UNIX domain sockets. It has been tested, but may become a possible entry point should parts of it be broken. If you come across a possible weak spot, please inform me immediately so that it can be fixed.) Kernel Kernel 2.0.x is recommended because its raw socket interface is known to be stable. Compiling on development kernels may or may not work. You may have to set the kernel configuration before you compile. IMPORTANT: Kernels prior to version 2.0.24 had a serious bug that allowed oversized IP packets to crash the system, while kernels prior to 2.0.32 crashed whenever certain badly fragmented IP packets were received. Even the 2.0.33 kernel had a denial-of-service vulnerability also in its fragmentation code. A fix is available. It is recommended that you upgrade your kernel to at least 2.0.35, or apply kernel patches to fix these problems. Terminal This program was designed to run on the Linux console. It should work on 80x25 xterms and rxvt windows. I'm still working on a SIGWINCH handler for X shells. Run this program from the console (text or xterm) or a high-speed terminal for best results. Starting with version 1.2.0, IPTraf will use the maximum number of lines on the terminal (however, only the first 80 characters on each line will be utilized) User Interface Operating the IP traffic monitor with reverse lookups enabled, but without the new rvnamed daemon running will cause lookups to block. This will cause keyboard response to become very slow and cause IPTraf to miss packets. Unless something is wrong with the system or resources are extremely low, rvnamed should start with no problem whenever the traffic monitor is initiated with reverse lookups turned on. See README.rvnamed for more details. IPTraf was designed and tested with ncurses 1.9.9e and ncurses 4.2. Earlier versions may cause undesirable screen behavior. There is also a little concern regarding the Backspace key. Apparently the backspace key mapping (KEY_BACKSPACE) is considered unreliable, and is marked as such in ncurses as late as 1.9.9e, although my tests on this version already worked. Tests for 1.9.4 failed; pressing the Backspace key yielded ^?. The Delete key works with no problem though. If you want the program to not recognize the Backspace key, you can enable the BSSETTING = DISABLEBS directive in the Makefile. Network Interfaces IPTraf currently includes support for Ethernet and SLIP/PPP interfaces. Work is still being done for other types of media. For Ethernet, IPTraf can receive packets in promiscuous mode (i.e. all packets on the LAN, regardless of their destination). Promiscuous mode is pointless on SLIP/PPP interfaces, since these things are point-to-point links. IPTraf imposes no additional load on the network (except for DNS traffic if reverse name lookup is enabled). Multiple Instances IPTraf 1.2 did not allow multiple instances of IPTraf running at the same time. With 1.3, this restriction is relaxed, and now operates on a per-facility basis. In other words, you can run multiple copies of IPTraf, but only one copy of each facility can run. The -f parameter to the iptraf command removes all tags, and will cause that instance to think it's the only one running. This option may be used to recover from an abnormal termination. Only the first instance started can change the configuration. COPYING AND DISTRIBUTION This software is open-source and is distributed under the terms of the GNU General Public License, Version 2 as published by the Free Software Foundation, Inc. See the accompanying COPYING file for details. FEEDBACK A WHATELSE file has been included in the distribution. It is about some other features I don't know whether to include or not. If you have anything to suggest, or if you discover a bug, please contact me. I would love to hear from you. If you think this program can potentially address a need but falls short, tell me the feature you desire and I will determine whether I will include it in this program or whether I will write another. Please mail to riker@mozcom.com Remember in this system, we improve our software when we know what users need and what they have. So please return feedback. It will be greatly appreciated. Gerard Paul Java riker@mozcom.com