#
# py-htbstat README file
# $Revision: 1.3 $
#
# Copyright (c) 2005 Dmytro O. Redchuk
# Copyright (c) 2005 VOLZ Llc
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
#
Introduction
============
py-htbstat is a tool set which helps to collect, monitor and analyze htb
classes statistic.
HTB statistic data are captured, processed and saved into RRD databases
along with HTB classes dumps. This statistic data then may be displayed by
CGI scripts and processed further by some checkers.
py-htbstat is a small set of scripts actually. Some part of functionality
was separated into a python module, HTBstat.
py-htbstat requires py-rrdtool (http://www.nongnu.org/py-rrdtool/,
http://www2.ldc.net/~dor/py-rrdtool-0.2.1.spec)
Below, in "Files" section, there are some descriptions and explanations.
And far below, in "Where to use" section you'll find some additional notes.
Files
=====
bin/
makestat.sh -- script to be run by cron, takes
`tc -s -d class show ...' output and passes it to
statsfill.py.
statsfill.py -- takes `tc -s -d class show ...' from makestat.sh
and fills RRD bases with stats. Also saves HTB
classes (using pickle module) in RRD bases
directory. Creates RRD bases on the fly.
NOTE, that these two are sample scripts only and
doesn't exist in rpm file.
cgi-bin/
dumpclass.py -- small CGI script which "dumps" HTB class pickled
by statsfill.py to browser screen. Also, if run
in box where your classes are configured, dumps
required class "in real time".
htbcheck.py -- this CGI script checks HTB classes hierarchy and
displays warning if some conditions are unmet
(from lighter one to the worst one imho):
sum of children's ceil higher than parent's ceil,
sum of children's rate higher than parent's rate,
sum of children's rate higher than parent's ceil.
htbstat.py -- 'main window' which allows to select (with
multiple selection possibility) classes,
timeranges, units, and draws a lot of pictures
from data stored in RRD bases. Allows to select
by class id or parent class id. For example, you
can select classes 33 (x:33 here) 48, 1049 etc.
and enjoy pictures for these, or you can view
pictures for classes, which parents are 21, 557,
2063, 3fa0 etc.
htbstatpic.py -- script, which accepts the same parameters, as `htbstat.py'
but returns a single picture (for the first class, if
multiple requested), can be included as
in other pages.
doc/
LICENSE -- GNU GPL.
README -- this file.
etc/
functions -- common functions, which are too uncommon to be
included into the module :-)
"Called" by htbstat.cgi.
htbstat.cgi -- config file for CGI scripts. "Called" by
htbstat.conf.
htbstat.conf -- 'main' config file, contains some kind of
documentation, too.
Configuration files are python commands lists
actually.
HTBstat/
HTBstat.py -- HTBstat module.
__init__.py -- __init__ for the module
STATpic.py -- this is a "picture module", contains a class
which instantiates "HTB pictures" objects.
py-htbstat-0.2.1.spec -- attempt to provide you with a spec for rpm
building :-)
(I use ALT Linux, http://www.altlinux.org/)
Installation
============
Place files to appropriate locations :-)
RPM install should work.
Where to use
============
This "scripts set" was designed to be used on linux bridges (I like linux
bridges and HTB on linux bridges:-) and you'll understand this having read
configuration files.
Configuration suppose you may have one or two interfaces with HTB classes
hierarchies configured: one interface is a common situation on routers,
configuration with two interfaces designed for bridge or router with
symmetrical HTB hierarchies -- in this case htbstat.py will draw you both
"incoming" and "outgoing" traffic on one picture.
And it is not of means to be used on boxes with two interfaces with different
hierarchies -- in this case you'll better create two configuration files sets
and scripts sets.
What to read further
====================
Be sure to read carefully configuration files -- there's a lot of
explanations. htbstat.conf then htbstat.cgi. And I tried to comment all
scripts and module files (however this work is not finished yet).
Known issues
============
Sometimes you may refresh browser page right at the moment when rrd bases are
being updated -- you'll see error message. Refresh the page again.
TODO
====
Would be nice to add to STATpic a possibility to summarize counters -- to
see sum of clients rates at one graph. Some improvements may be added to
HTBstat (STATpic) like specifying picture dimensions in config file and
passing as arguments to STATpic etc. And there can be a lot of analyzing
enhancements... Any other ideas, please?
Author(s)
=========
Dmytro O. Redchuk , with a great help of all
VOLZ/LDC team.
Please, do not blame me to much -- this is my the first Python code piece :-)
Actually, I have been working (and I am working further) on more interesting
code -- HTB configurator -- and this monitoring-only scripts are much like
side effect :)