Contents:
1) Purpose/Features
- What BRICKreporter is doing
3) Configuration
- preparations to be done
- via config-file
- via command-line
switches
4) Reports
- The different reports and how to read them
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.
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.
Preparations:
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.
The config-file:
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 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 |
| = account 21th March '99 | = account full April '99 | = account full year 1998 |
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 a date has been set.
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 a date has been set.
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]:
| Short switch | Long switch | Function |
| -c <filename> | --config-file <filename> | Specify an alternative config-file |
| -d <[DD.]MM.YYYY> | --date <[DD.]MM.YYYY> | Specify the date to account for |
| -l <COMPACT|LONG|SHORT> | --level <COMPACT|LONG|SHORT> | Set/override the output level |
| -f <HTML|TEXT|BOTH> | --format <HTML|TEXT|BOTH> | Set/override the output format |
| -? | --help | Print help text / usage |
| -v | --version | Print version number |
You can omit any [options] and just start BRICKreporter with:
brickreporter <logfile-to-analyze>
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.
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; maybe the program uses some defaults you didn't think of.
We now wish you a successful accounting.
© 1999, acelab