2005-11-13
Jason Schoonover
Throughput portion of Unnoc

Throughput was added into unnoc in 1.0.0

	1. Explanation
	2. Configuration
	   a. automatic
	   b. manual
	3. Viewing

1. Explanation

This part of unnoc will printout current values and peak values for a 
given network interface. The output looks like this:


   Network Throughput at 12:02:02
   Current Inbound Traffic 			30.889 kB/s (247.111 kbps)
   Current Outbound Traffic 			155.369 kB/s (1.214 Mbps)
   Peak Inbound Rate over the past 24 hours 	293.940 kB/s (2.296 Mbps) at 10:53:02
   Peak Outbound Rate over the past 24 hours 	377.576 kB/s (2.950 Mbps) at 11:33:02


In previous versions of Unnoc, the throughput checking was the only way to
monitor a network interface on a device.  It was very simple as well,
you had to check it on time, every time, or the math would be messed up.
You could also only specify one interface per device, only.

This has changed as of Unnoc 1.0.6.

As of Unnoc 1.0.6, every network interface that unnoc knows about is
capable of this.  So that means that you could print this information
out for any one of your network interfaces for your wireless access
points, firewalls, switches, servers--any network interface that unnoc
knows about, it will keep all of these statistics. It is always
displayed at the top of the network interface page, with graphs below
it.

To print this information out, you have to call only one function:

	<?php display_throughput ('goliath', 12); ?>

That will print out the information in the format above, with a current
time stamp.  You only need to know the interface number (in this case,
'12').  The simplest way to find this information out is to click on the
host in unnoc and see what interface number is being monitored in the
show_interfaces section.  If you do not specify an interface, it will go
for the first interface it finds for a host.


2. Configuration

There are two ways to configure an interface, automatic and manual.
Automatic happens, well, automatically.  If unnoc is monitoring a device,
then it will keep this information already, so you don't' even have to
specify it.  Manual is for other instances, details are below.

There is only one configuration option for the throughput part of unnoc,
it is how often the interfaces get reset:
	
	interface_reset

		When do the peak values get reset, valid values are a
		time, in the format HH:MM

		Example:  interface_reset = 03:31

		That would reset all interface's peak values at 3:31 AM

The algorithm is much better than previous version and it is recommended
to run it more often on interfaces that you wish to watch the throughput
more closely (specifically, interfaces that are displayed on the front
page).


In previous versions you had to explicitly specify which interfaces on
which hosts to monitor, via the throughput array.  This has all changed
as of 1.0.6, if you wish to monitor a particular interface, then you
should specify that in the host{} directive, like this:

	host {
		hostname = gateway-1
		community = public
		description = Main Cisco 2600 Router
		interfaces = 12,3
		primary_interface = 12
	}

With the above setting, only the interfaces 12 and 3 will be monitored
and displayed.  There are a few ways to figure out which interfaces you
need to monitor, details are below.

If you did not specify 12 and 3 in the above configuration, then all
interfaces would be monitored.

a. automatic configuration
	
As stated before, Unnoc will keep this information for every device that
it knows about.   If you have a device that you wish to display the
interface information on the host view page, then specify that
particular interface with the 'primary_interface' option on the host
configuration.

b. manual configuration

Sometimes the network interfaces will not get read properly.  Sometimes
devices do not report the interfaces as being 'up' even though they are,
or the 'type' of interface is listed wrong (listed as loopback for
instance, even though it's an ethernet interface).  So if you add your
firewall/router/whatever and you notice that no network interfaces come
up, then chances are this is one of those hosts.

The best way to quickly see how many interfaces are on a particular
host, use the 'snmpwalk' executable that comes with Net-SNMP

	## this is a walk of the ifDescriptions
	snmpwalk -c public -v 1 localhost 1.3.6.1.2.1.2.2.1.2

If that doesn't tell you much info, you can walk the entire interface
table
	
	snmpwalk -c public -v 1 localhost 1.3.6.1.2.1.2.2.1

That should tell you what interfaces are alive and which are not.


3. Viewing

You can either click on the interface information listed (if it's
automatic), or you can call it from some other page with the
display_throughput() function.

You can also call in/out and peak values separately if you wanted
to, with these functions:

	check_tp_inbound()	- displays inbound
	check_tp_outbound()	- displays outbound
	check_tp_peak_in()	- displays peak inbound
	check_tp_peak_out()	- displays peak outbound

Each functions syntax is identical to display_throughput()


One thing to note, if you're in/out seems reversed, you're probably
monitoring the wrong interface.  On a router for instance, you would
want to monitor the 'external' port, not the 'internal' one, because the
internal SENDS the information the external RECEIVES.  If you're sure
you're monitoring the right interface, you can always reverse the
inbound/outbound functions above.  If you can't seem to get to the
proper value of in/out, then you can always reverse the network
interface with the interfaces_reverse directive, like this:

	host {
		hostname = router
		community = public
		interfaces = 1,3,4,5
		interfaces_reverse = 3,4
	}

I've included several example files in the examples/ directory.


vim:tw=72:wm=1