========
README
========

Project home page - http://ibmonitor.sourceforge.net
On freshmeat      - http://freshmeat.net/projects/ibmonitor/
Mailing List      - ibmonitor-user@lists.sourceforge.net
  Visit http://lists.sourceforge.net/lists/listinfo/ibmonitor-user
  to subscribe/unsubscribe
Contact Author: rohan@almeida.in

ABOUT
-----
ibmonitor is an interactive linux console application which shows 
bandwidth consumed and total data transferred on all interfaces.

Its main features are:
  - Shows received, transmitted and total bandwidth of each interface
  - Calculates and displays the combined value of all interfaces
  - Displays total data transferred per interface in KB/MB/GB
  - Bandwidth Values can be displayed in Kbits/sec(Kbps) and/or KBytes/sec(KBps)
  - Can show maximum bandwidth consumed on each interface since start of utility
  - Can show average bandwidth consumption on each interface since start of utility
  - The output with all features (max, avg and display in Kbps and KBps)
    easily fits on a 80x24 console or xterm
  - Can interactively change its output display format depending on key
    pressed by user.

This project is different from existing similar utilities in that it can
show the values in Kbits and Kbytes simultaneously. It also displays
the total data transferred in KB/MB/GB dynamically shifting the unit
to adjust available field width. Also command line switches are available 
which allow to choose whether to display maximum and average bandwidth. 
It will respond to certain key presses while running and can dynamically 
change the output display format.
eg. keypress m -> toggle view/hide max of all interfaces

Future plans include, to make it display dynamic multi-colored graphs 
per interface using svgalib, and also make it respond to signals so 
that it can communicate its values to other programs which would 
need such data. As an example, a web CGI script which sends a signal 
to ibmonitor, gets the values and prints out a nicely formatted HTML page.
(I maybe need to use rrdtool here)


REQUIRED
--------
  The ibmonitor perl script requires the following perl modules:
  1) Term::ANSIColor - Usually available with most linux distros
  2) Term::ReadKey -needed for the "interactiveness" of ibmonitor.
  		You can download Term::ReadKey from CPAN.
		Just cut and paste the following link into your browser:
		http://search.cpan.org/search?query=Term%3A%3AReadKey&mode=module
  3) Time::HiRes - usually available with some distros
		Otherwise, download from CPAN.
		http://search.cpan.org/search?query=Time%3A%3AHiRes&mode=module
	

  Currently, this utility will only run on Linux distros which support
  the /proc filesystem due to the fact that ibmonitor reads
  the file "/proc/net/dev" for the byte counter values.
  In case you are on a variant of UNIX(but not Linux), which supports 
  the /proc filesystem, then you need to check with your local system expert
  to find out which file is similar to the file "/proc/net/dev" on a
  Linux system.

  I will try to list all possible OSes here with the /proc file
  which should get ibmonitor running on your system.
  Any help regarding this would be much appreciated.
  Contact me at - Rohan Romanus Almeida <arcofdescent@gmail.com>


USAGE
  ibmonitor is a command line program which will run
  on a linux console or xterm (rxvt, konsole, gnome-terminal, etc)

  usage: ibmonitor [--bits] [--bytes] [--max] [--avg] 
                   [--interval n] [--data] [--colors | --nocolors] 
                   [--dev regex] [--file proc] [--help] [--version]

  The following command line options (and their explanation) are available:

  --bits            -> Show output values in KBits/sec. This is the default.
  --bytes           -> Show output values in KBytes/sec
  --max             -> Show maximum values per interface
  --avg             -> Show average values per interface
  --interval n      -> Set time interval as n seconds. The default is 2 seconds.	
  --data            -> Show data transferred in KB/MB/GB
  --colors          -> Show some fancy coloring! This is the default
  --nocolors        -> No fancy coloring please!
  --dev regex       -> Show output from device matching regex
  --file proc       -> Specify which file to use in the proc filesystem  
                       for the interface byte counter
  --help            -> Show help and exit
  --version         -> Show version number and exit

  While running, ibmonitor can also read the input key from the user
  and dynamically change the output display format depending on the key
  pressed. 

  The following keys are supported. Note that ibmonitor responds directly
  to the single keystroke. ie. 'Enter' key need not be pressed.
  NOTE: This will only work if you have the Term::ReadKey Perl module
        installed and working, hence the requirement.

  q         -> [q]uit
  1 - 9     -> Set sleep time interval(in seconds) to the digit entered
  m         -> Toggle display of [m]ax bandwidth
  a         -> Toggle display of [a]verage bandwidth
  i         -> Toggle display of values in KB[i]ts/sec (Kbps)
  y         -> Toggle display of values in KB[y]tes/sec (KBps)
  d         -> Toggle display of [d]ata transferred
  s         -> Shift interface up/down.
               This should be followed by the interface number,
               and then the direction (u or d)
  r         -> [R]eset all values
  ?/h       -> Help Screen for interactive commands