Read Me

CHANGELOG

$Id$

20070830 ewn Thanks to Hondza (sedaj2 AT gmail DOT com) for making me
             aware of a bug that caused a segfault when interfaces were
	     added or removed from the system. This was due to the
	     linked lists becoming unstable when this happened. (I had
	     never thought the program might be running when this
	     happened, but I can see this is an obvious problem, thanks
	     for bringing it to my attention!). Changes also to the
	     Makefile so that packaging is easier.

20071015 ewn Added some postgres interfacing so that support can be
             included for this. Postgres often requires a bit more work
	     so this may not be fully supported for a while.

HISTORY

  This used to be a single .c file which would pull the values from BSD
  interfaces. I then did an almost duplicate for linux /proc/net file
  system to get values from there too.
  
  More recently I have merged the two into a single program, which
  compiled on a BSD platform will pull values from BSD interfaces and do
  likewise on a linux platform. Since I don't have access to other
  platforms I cannot make it more portable.

  Untar into a directory of it's own, then issue one of the make
  commands below.

tar zxvf netmon-0.03.tar.gz

  Rather than using a autoconf script for something that's a rather
  simple project, the different options can be built using a single make
  command. The following have been created:

make linux
make openbsd
make linux-mysql
make linux-sqlite

  Once one of those is completed, simply run ./netmon.

  If you chose a DB option, please see the section below on running with
  a DB.


DATABASE

  To work with the database, the environment NETMONDB must be set.

  Also the environments 

NETMON_DB_USER=username
NETMON_DB_PASS=password
NETMON_DB_SERVER=servername
NETMON_DB_DATABASE=databasename

  *******************************************************************
  *******************************************************************
  ****                                                           ****
  **** !! WARNING !! WARNING !! WARNING !! WARNING !! WARNING !! ****
  ****                                                           ****
  **** If you think it's a possible security risk to leave the   ****
  **** database password in the environment while other things   ****
  **** happen then please be sensible and don't use a common     ****
  **** password that you're using for other compromising things. ****
  **** Please make a lower privileged user for the database      ****
  **** interactions.                                             ****
  ****                                                           ****
  *******************************************************************
  *******************************************************************


  A table is required to accept the insertions, this can be created
  using the following schema:

create table netmon( 
netmon_id integer not null auto_increment,
netmon_date timestamp default now(), 
netmon_interface varchar(255) not null default '', 
netmon_ibytes bigint  not null default 0, 
netmon_obytes bigint not null default 0, 
netmon_ipackets bigint not null default 0,
netmon_opackets bigint not null default 0, 
index( netmon_interface ),
primary key( netmon_id ) );

create table netmon( 
netmon_id integer not null auto_increment,
netmon_date timestamp default now(), 
netmon_interface varchar(255) not
null default '', 
netmon_hostname varchar(255) not null default '',
netmon_ibytes bigint not null default 0, 
netmon_obytes bigint not null
default 0, netmon_ipackets bigint not null default 0, 
netmon_opackets bigint not null default 0, 
index( netmon_interface ), 
index( netmon_hostname ),
primary key( netmon_id ) 
);

Postgres setup

  Assuming that you have already installed postgres, one can create a
  database for netmon to use with the following as postgres
  administrator:

  createdb -U netmon

  create role netmon with password 'netmon' login;
  create database netmon;
  grant all on database netmon to netmon;

Schema

-- create the table itself
create table netmon( 
netmon_id serial not null,
netmon_hostname varchar(255) not null default '',
netmon_date timestamp default now(), 
netmon_interface varchar(255) not null default '', 
netmon_ibytes bigint  not null default 0, 
netmon_obytes bigint not null default 0, 
netmon_ipackets bigint not null default 0,
netmon_opackets bigint not null default 0,
primary key( netmon_id ) );

-- create the index for the interface, should the user wish to select
-- based on the interface frequently.
create index netmon_interface_idx on netmon ( netmon_interface );


  Running netmon --database will tell netmon to insert the current
  values into the database. This is useful if you do not wish to leave
  netmon running in the background, but wish to capture the interface
  statistics regularly, for example, for use with your own graphing
  tools or report generations.


MRTG

  To use with mrtg, just call netmon and then the interface name. For
  packets count add 'p' to the end of the command line.

Title[fxp0]: fxp0 bytes - ADSL
Options[fxp0]: bits,growright
Target[fxp0]: `/usr/local/bin/netmon fxp0`
PageTop[fxp0]: fxp0 bytes - ADSL
MaxBytes[fxp0]: 100000000
Ylegend[fxp0]: bytes
ShortLegend[fxp0]: bytes
XSize[fxp0]: 350
YSize[fxp0]: 150
Legend1[fxp0]: bytes 
LegendI[fxp0]: input 
LegendO[fxp0]: output 
WithPeak[fxp0]: ymwd

For example:

	$ /usr/local/bin/netmon eth0 p

  Use like this is good for scripts that just need to get a byte count
  and then exit. For a slight performance improvement specify the full
  path to netmon so the shell does not have to search the path to find
  the executable.

  With version 0.02 a script has been added to generate the MRTG
  configs. This can be used with a new option '--list':

	perl mrtg_cfg.pl /usr/local/mrtg/data $( ./netmon --list )

  The script takes as first argument a path to the location of the MRTG
  data and the following arguments are the names of the interfaces.
  
  Support, updates etc, ed (at) s5h (dot) net, http://s5h.net