BRICKreporter documentation
===========================

Contents:
1) Purpose/Features
   - What BRICKreporter is doing
2) Installation
3) Configuration
   - preparations to be done  
   - via config-file
   - via command-line switches
4) Reports
   - The different reports and how to read them
5) BRICKreporters logfile 



1) Purpose/Features
-------------------

The main purpose of BRICKreporter is to analyze ip-traffic and to
generate ip-traffic- and accounting-reports from logfiles written
by BinTec BIANCA/BRICKs. See section C) for a description of the
various results. 

BRICKreporter has the ability of generating source-to destination
destination-to-source-reports, both for ip-addresses and BRICK-
interfaces. 

These reports can be in detailed form (every connection) or in
short form (cumulative, which means subtotals for every source
address in the source-to-destination report and vice versa).

Moreover BRICKreporter generates Top-Ten-traffic reports and
a report for traffic by services. The reports contain bytes
and percent for your overview. 

As a feature, you have the ability to turn on DNS-lookups
(resolving of addresses to hostnames) both, for source and for
destination addresses seperateley. 

Of course you can specify the networks/addresses which should be 
accounted and as a plus you also can specify a list of networks/
addresses which should be dropped from accounting. 

See the next section about how to configure all this. BRICKreporter 
defaults to reasonable values for the most options, if not specified.



2) Installation
---------------

Installation is easy. After you have untarred/gzipped the 
archive-file simply run the shell-script ./install.sh
which will do the rest for you and install BRICKreporter
to /usr/local/brickreporter. (A link to the binary is set
to /usr/local/bin/brickreporter or /usr/bin/brickreporter.



3) Configuration
----------------

Actions to take prior to using BRICKreporter:
Before you can use BRICKreporter to analyze your logfiles, you
have to setup some options on the BRICK itself and your loghost,
if not already done.

You must tell the BRICK where it should sent the accounting
information to. You set this up using BRICK Setup -> System ->
External System Logging. Add an entry for your server running
the syslog daemon. (Be sure that the syslogd on your loghost
accepts input from other hosts.)

The next step to do is to enable ip-accounting on the BRICK
for every interface you want to be accounted. You can do 
this in the IP -> Advanced Settings menue of your WAN-Partners/
Interfaces. Now your system is set up for accounting and you
can start using your BRICKreporter.
 
BRICKreporter allows you a flexible and powerful configuration for
manipulating the the verbosity and formats of the generated output.
BRICKreporter mainly uses a configuration-file to specify the program
behaviour but also accepts command-line switches for the main options.
The default config-file resides in /etc/brickreporter.conf but you
can specify an alternative config-file on the -c command line switch.
You can specify the following variables in the config-file:

NETS_TO_ACCOUNT = <net:netmask1>, <net:netmask2>, <net/bitmask> 
NETS_TO_DROP = net:netmask1, ... 
ACC_DATE_DAY = <integer>
ACC_DATE_MONTH = <integer>	
ACC_DATE_YEAR = <integer>	 
BRICK_NAME = <string>    
OUTPUT_FORMAT = <TEXT | HTML | BOTH>
OUTPUT_TEXT_FILENAME = <filename>
OUTPUT_HTML_FILENAME = <filename>
OUTPUT_LEVEL = <COMPACT | SHORT | LONG>
RESOLVE_SRC_IP = <NO | YES>
RESOLVE_DEST_IP = <NO | YES>
SERVICES_WATERMARK = <float> 

Each of these will be explained below:

NETS_TO_ACCOUNT = value-1, value-2, value-n
 Description:
 Define the networks and/or hosts you want to be accounted. 
 "Account" means, traffic from or to these networks are counted.
 This will be usually your local network but can be cut down to
 one single host if you like to. Entries must be comma-seperated and
 must be in one line.
 The syntax for these entries is: address/bitmask or address:netmask
 Be sure to use the "/" for bitmask entries and the ":" for quaddotted
 netmask and to seperate multiple entries by a comma.  
 Examples: 
 192.168.10.0/24               -> Account the net 192.168.10.0-255
 192.168.10.5/32               -> Account the host 192.168.10.5
 192.168.10.64:255.255.255.192 -> Account the subnet 192.168.10.64-127 
 Hint: If neither a records source- nor destination-address is matching
 the NETS_TO_ACCOUNT-list, it will be dropped, even if they are not
 on the NETS_TO_DROP list. The purpose of the NETS_TO_DROP list is i
 to exclude addresses from your otherwise accounted nets.
 If not set, nothing will be accounted by BRICKreporter.


NETS_TO_DROP = value-1, value-2, value-n
 Description:
 Define the networks and/or hosts you do NOT want to be counted, i.e.
 which will be dropped. You can drop both local or remote addresses,
 if you do not want them to show up in the reports. 
 Entries must be comma-seperated and must be in one line. 
 You can leave NETS_TO_DROP unset, if you don't want to drop any
 records.


ACC_DATE_DAY = value		# 1-31
ACC_DATE_MONTH = value		# 1-12
ACC_DATE_YEAR = value		# 4-digit year 
 Description:
 Set the time period for which accounting should be done.
 You can leave away any date-field from top to bottom. That means:
 a) You give day, month and year = only that day is accounted 
 b) You only give month and year = that full month is accounted
 c) You only give the year       = that full year is accounted
 d) You give none of the above   = all information is accounted (default)
 Examples:    
 ACC_DATE_DAY = 21       ACC_DATE_DAY =         ACC_DATE_DAY =
 ACC_DATE_MONTH = 3      ACC_DATE_MONTH = 4     ACC_DATE_MONTH =
 ACC_DATE_YEAR = 1999    ACC_DATE_YEAR = 1999   ACC_DATE_YEAR = 1998
 = acc. 21th March '99   = acc. full April '99  = acc. full year 1998
 If not set, all information present in the logfile will be accounted.
 

BRICK_NAME = brickname
 Description:
 Set this to the name of the BRICK you want to analyze (as it appears in the
 logfile, that means case is sensitive). 
 If not set, all information present in the logfile will be accounted.

 
OUTPUT_FORMAT = TEXT | HTML | BOTH
 Description:
 Set the output format of BRICKreporter to one of the values TEXT, HTML or BOTH.
 If you choose HTML the report will be generated in html-format only. If you
 choose TEXT the report will be in ASCII-format only. If you choose BOTH
 here, two files will be generated, one in html-format and the other in ascii.
 If not set, BRICKreporter defaults to TEXT.
 

OUTPUT_TEXT_FILENAME = filename
 Description:
 Set the filename for the ascii-output
 If not set, BRICKreporter defaults to ./brickreporter.txt or to
 ./brickreporter-DD.MM.YYYY.txt, if you have set a date


OUTPUT_HTML_FILENAME = filename
 Description: 
 Set the filename for the html-output
 If not set, BRICKreporter defaults to ./bricktreporter.html or to
 ./brickreporter-DD.MM.YYYY.html, if you have set a date


OUTPUT_LEVEL = COMPACT | SHORT | LONG
 Description:
 Set the output level format to one of the values COMPACT, SHORT or LONG
 COMPACT generates Top-Ten lists and traffic by service overview
 SHORT generates records for every source address plus the above
 LONG also adds records for every source to destination connection plus the
 above 
 If not set, BRICKreporter defaults to COMPACT.


RESOLVE_SRC_IP = NO | YES
 Description: 
 Should the source-ip-addresses be resolved to hostnames?
 Warning: Resolving all hostnames in a huge logfile may take a very, 
 very long time (though CPU-time is kept small anyway). 
 Resolving is reasonably fast for COMPACT reports since only the
 the Top-Ten have to be looked up.
 If not set, BRICKreporter defaults to NO


RESOLVE_DEST_IP = NO | YES
 Description:
 Should the destination-ip-addresses be resolved to hostnames?
 Warning: Resolving all hostnames in a huge logfile may take a very, 
 very long time (though CPU-time is kept small anyway). 
 Resolving is reasonably fast for COMPACT reports since only the
 the Top-Ten have to be looked up.
 If not set, BRICKreporter defaults to NO


SERVICES_WATERMARK = 0.5
 Description:
 The SERVICES_WATERMARK defines the percentage of total traffic a
 service must reach to be listed in the "Traffic by service"-report.
 Services with less traffic are otherwise cumulated under "MISC".
 A (default) value of 0.5 % or greater is reasonable and helps you
 keeping your traffic report clear. If you really want to see all
 services in the report, set this to 0 
 If not set here, BRICKreporter defaults to 0.5


The command line switches:
The BRICKreporter usage is: brickreporter [options] <logfile-to-analyze>
Options given on the command line override the values in the config-
file so you may set your main defaults there.

BRICKreporter accepts the following command line switches as [options]:
-c | --config-file <filename>     : to specify an alternative config-file
-d | --date DD.MM.YYYY or MM.YYYY : to specify date to be accounted
-l | --level <COMPACT|LONG|SHORT> : to specify/override the output-level 
-f | --format <HTML|TEXT|BOTH>    : to specify/override the output-format
-? | --help			  : print a help screen and exit
-v | --version			  : print the version number and exit
You can omit any [options] and just start BRICKreporter with:
brickreporter <logfile-to-analyze>



4) The reports
--------------

BRICKreporter generated one file per output-format (text and/or html)
each containing several reports, depending on the output-level you chose:
COMPACT format will generate the following reports:
- Traffic by service (in bytes and percent)
- Top-Ten traffic by source address (in bytes and percent)
- Top-Ten traffic by destination address (in bytes and percent)
- Top-Ten traffic by source interface (in bytes and percent)
- Top-Ten traffic by destination interface (in bytes and percent)

SHORT format will generate the five reports from above plus:
- Traffic report for source addresses with a subtotal for each address
- Traffic report for destination addresses with a subtotal for each address
- Traffic report for source interfaces with a subtotal for each interface
- Traffic report for destination interfaces with a subtotal for each interface

LONG format will generate the nine reports from above (COMPACT+SHORT) plus:
- Traffic report by source address to each destination address with subtotals
- Traffic report by destination address to each source address with subtotals
- Traffic report by source interface to each dest. interf. with subtotals
- Traffic report by dest. interface to each source interf. with subtotals

You should keep in mind that the LONG (and even the SHORT) format will
get very long and only make sense if you want to see which address/interface
had connections to what other addresses/interfaces. If you just need an
overview, choose the COMPACT form.


5) BRICKreporters logfile
-------------------------

Whenever BRICKreporter is run it will write status information to
the logfile in /var/log/brickreporter.log

In this logfile BRICKreporter tells you:
- when it was started
- which options were used (output format- and level)
- if some your setting have been invalid and thus set to default
- how many records have been accounted
- how many records have been dropped (if filtering)
- how many DNS-lookups took place and how many of them timed out 
- how much CPU-time BRICKreporter used for the accounting process
- when it ended the process

You will normally not need these information, but if you think
that something is not running as you expected it to run, take
a look in this logfile.

We now wish you a successful accounting.

(c) 1999, acelab

