jnettop/README

   1 This is jnettop 0.13.0.
   2 It's a package, which should do simmilar job for network as top does for
   3 processes.
   4
   5 -- Introduction --
   6
   7 After administering various networks I decided to write this piece of code,
   8 becouse I didn't find anything that was simmilar or suitable for my purpose.
   9 I often needed to watch traffic on the outbound router by the times our line
  10 was getting red and see, what's going on there and whether is it right.
  11 I hope, somebody out there will find this tool usefull too.
  12 Just in case you wanted to write me any comments, hints, postcards, herritage
  13 announcements, love, wish, abuse etc., feel free to use my email, j@kubs.cz,
  14 please include "jnettop" in the subject of your mail(!!).
  15
  16 -- Installation --
  17
  18 Download the sources (http://jnettop.kubs.info), unpack and decide, whether
  19 you want:
  20
  21   support for NCURSES display (default is yes)
  22   support for logging into SYSLOG (default is yes)
  23   support for UIA protocol (default is no) (see README.UIA for more info)
  24
  25 if you don't want the default behaviour for any of the above options, specify
  26
  27   --without-ncurses, --without-syslog, --enable-uia
  28
  29 respectivelly to configure script. Make as usual.
  30
  31 -- FreeBSD Notes --
  32
  33 Is jnettop crashing under your FreeBSD? Try passing
  34 --disable-multithreaded-resolver to configure script and recompile.
  35
  36 -- Aggregation --
  37
  38   (What is it?)
  39
  40 Aggregation is a way, how to modify packet classicication rules. There are
  41 two types of aggregation in jnettop: host and port. If there is port
  42 aggregation enabled, it means, that all packets seem to come(go to) same port
  43 numbers. If there is host aggregation enabled, it means, that all packets
  44 seem to come(go to) same host. Let's have an example:
  45 Suppose we have following configuration:
  46
  47                                                              +--- host0
  48   internet ----- addr1 (eth0) --- router --- addr2 (eth1) ---+--- host1
  49                                                              +--- host2
  50
  51 i.e. typical border router with eth0 interface looking into internet and
  52 eth1 interface looking to intranet. Suppose we're running jnettop on router
  53 sniffing on interface eth0. To see how many bytes every host consumes out
  54 of the internet connection, we enable remote host aggregation and local port
  55 aggregation. i.e. All internet will behave as one endpoint and all programs
  56 on one host will, too, behave as one endpoint. This way, every stream we see
  57 in jnettop will be from one of the hosts in intranet to a public internet.
  58 Aggregation is very powerfull laser-knife in network traffic analysis.
  59 I understand, that it is not very user friendly implementation in jnettop and
  60 I will gratefully welcome every suggestion on how to make this topic clear and
  61 more clear-to-use.
  62
  63 -- .jnettop configuration file --
  64
  65   (How can I configure packet filters that apply prior to processing
  66    packets)
  67
  68 Since version 0.6, jnettop package scans your home directory for a file named
  69 ".jnettop" and reads possible packet filters. Syntax of the configuration
  70 file is (at least I hope) obvious out of the example provided in .jnettop file
  71 included in distribution. The file consists of lines beginning with keywords.
  72 Each keyword can have various parameters. Following keywords were implemented
  73 so far:
  74
  75   variable      "<name>"        "<value>"
  76
  77     this keyword introduces new string variable of name <name>. This variable
  78     is assigned value of <value>. Variables can be used in rule specifications
  79     to shorten them and make them more readable.
  80     ex.
  81
  82       variable  "intranet"      "net 192.168.0.0/16"
  83
  84   rule          "<name>"        "<packet filter specification>"
  85
  86     this keyword defines new packet filter rule of name <name>. Packet filter
  87     syntax conforms to that of libpcap library or tcpdump program. Explanation
  88     of the syntax can be found in manual page of tcpdump package. Specification
  89     undergoes variable substitution. Each string of the form "${identifier}" is
  90     expanded to the value of the variable named "identifier". The variable
  91     must be defined PRIOR to the definition of the rule in the configuration
  92     file. Given the previous example of variable keyword, you can use:
  93
  94       rule      "source is intranet"    "src ${intranet}"
  95
  96 After you start jnettop, you can use the "f" key to select active filter used
  97 PRIOR to any packet processing. This filter is applied BEFORE any statistics
  98 are computed, so even the total BPS is computed only out of the packets, that
  99 pass the filter(!!).
 100
 101 Since version 0.8, jnettop supports "interface" keyword, which specifies
 102 which interface to listen after you start it up. Example:
 103
 104   interface     "eth0"
 105
 106 Since version 0.9, jnettop supports following new keywors:
 107
 108   local_aggregation     [none|host|port]
 109
 110     this keyword sets startup local aggregation value
 111     ex.
 112
 113       local_aggregation  port
 114
 115   remote_aggregation    [none|host|port]
 116
 117     this keyword sets startup remote aggregation value
 118     ex.
 119
 120       remote_aggregation host
 121
 122   select_rule   "<name>"
 123
 124     this keywors sets rule, that is enabled on startup
 125     name is the name of previously(!) defined rule (by "rule" keyword)
 126     ex.
 127
 128       select_rule "source is intranet"
 129
 130 Since version 0.11, jnettop supports multiple resolvers. This can be configured
 131 thru "resolve" keyword in configuration file:
 132
 133   resolve_rule "<network ip>" "<network mask>" [normal|external] ("<extscript>")
 134
 135     this keyword configures resolver, so that it uses the appropriate method
 136     of resolving for specified network. If this method fails, next one matching
 137     is used.
 138     ex.
 139
 140       resolve_rule "192.168.1.0" "255.255.255.0" normal
 141       resolve_rule "192.168.1.0" "255.255.255.0" external "jnettop-lookup-nmb"
 142
 143     this will cause jnettop to use normal DNS lookup for all 192.168.1.0/24 address-
 144     es first. If nothing is found, than external program "jnettop-lookup-smb"
 145     is used.
 146     if end of all rules is reached, normal DNS lookup is used.
 147
 148   resolve [on|off]
 149
 150     enables/disables resolving completelly
 151
 152 Since version 0.12, jnettop supports explicit list of local networks. Local
 153 networks then appear on the left side of display:
 154
 155   local_network "<network ip>" "<network mask>"
 156
 157     this keyword configures packet classifier, so that hosts matching this
 158     classification will be considered local.
 159
 160 The pathname of configuraton file can be overrided by specifying -f command
 161 line parameter.
 162
 163 -- libpcap dependency explanation --
 164
 165   (Why cannot I switch interfaces while running jnettop. I've seen this
 166    feature on a screenshot)
 167
 168 There are various libpcap versions out there with different capabilities.
 169 Notably there are 0.6.2 and older, which don't support interface discovery.
 170 With these versions of libpcap, you won't be able to switch between interfaces
 171 while running jnettop. Anyway, you can use "-i" parameter to specify which
 172 interface to listen on (since jnettop 0.2).
 173 With libpcap version 0.7 and younger, you will be able to switch between
 174 various interfaces while running jnettop.
 175
 176 If you want to get newer version of libpcap, go to http://www.tcpdump.org to
 177 get sources or you can find newer versions in RPMs on http://rpmfind.net
 178
 179 -- glib2 dependency --
 180
 181   (Won't there be port for glib < 2 versions?)
 182
 183 No. This package is heavily dependant on thread functions contained in glib2.
 184 I believe, that there are (will be) various platforms for which glib2 is ported
 185 and thus prefer to depend on generic threading capabilities of glib2 to meet
 186 less portability problems later.
 187 Glib2 is now available in RPMs for RedHat (and simmilar), DEBs for Debian and
 188 .tar.gz for the others.
 189
 190 -- UNKNOWN traffic --
 191
 192   (Jnettop displays a lot of UNKNOWN traffic and UNK. protocol)
 193
 194 Jnettop was done as basic analysis tool and does not interpret most of the
 195 protocols on Internet. Namely it can only interpret TCP/UDP/IP (v4 as well as
 196 v6 since 0.10) on EtherNet or Linux "any" device. This is sufficient for vast
 197 majority of linux users (=me .-)). In case you want me to add support for
 198 another encapsulation (802.11, etc...), please send me output of jnettop -d
 199 and a piece of tcpdump dumpfile with examples of packets. I'll do my best :)
 200 In case you want me to add support for another higher-level protocol
 201 (IPX, AppleTalk,...), please, send me a vote for that protocol.
 202
 203 -- PORTABILITY --
 204
 205   (Does Jnettop work under system X on computer Y)
 206
 207 For portability description, please, see PORTING file. There is an up-to-date
 208 status of portability issues. Generally, I'd like jnettop to be working on
 209 any system, which has glib2, pcap and ncurses ports.
 210
 211 -- content filtering --
 212
 213   (What the hell is that?)
 214
 215 Jnettop attempts to "understand" what communication is in the TCP/UDP data and
 216 displays this information along the stream. For example it can recover URL from
 217 a HTTP request or addresses of ongoing SMTP session. Content filtering is
 218 enabled by default and can be disabled while running. There can be performance
 219 problems on a very busy server which would cause various packets to be dropped.
 220
 221 -- 100% CPU usage --
 222
 223   (Why does jnettop consume all CPU time?)
 224
 225 Libpcap's features don't include reading a packet with timeout. On some systems
 226 this can be overcomed by using select() call. On others, we loop between non-
 227 blocking read and thread_yeald() function (notably BSD). On these systems (BSD)
 228 jnettop consumes all available CPU time, but should behave nicely, so that
 229 it consumes all time up to 100%. Other processes should have theire appropriate
 230 time. This behaviour does not include Linux
 231
 232 Copyright (C) 2002, 2003, 2004, 2005, 2006 Jakub Skopal
 233 Portions of the package are taken from the tcpdump project and their rights are
 234 held by their respective owners stated in the beginning of the files.
 235
 236 $Header$
 237