ossp-pkg/flow2rrd/flow2rrd.pod
##
## OSSP flow2rrd -- NetFlow to Round-Robin Database
## Copyright (c) 2004 Ralf S. Engelschall <rse@engelschall.com>
## Copyright (c) 2004 The OSSP Project <http://www.ossp.org/>
##
## This file is part of OSSP flow2rrd, a tool for storing NetFlow data
## into an RRD which can be found at http://www.ossp.org/pkg/tool/flow2rrd/.
##
## 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, or contact Ralf S. Engelschall <rse@engelschall.com>.
##
## flow2rrd.pod: manual page (language: POD)
##
=pod
=head1 NAME
B<OSSP flow2rrd> - NetFlow to Round-Robin Database
=head1 VERSION
B<OSSP flow2rrd> FLOW2RRD_VERSION_STR
=head1 SYNOPSIS
B<flow2rrd>
[B<--config=>I<file>]
B<--store>
B<flow2rrd>
[B<--config=>I<file>]
B<--graph>
I<host>[C<:>I<target>]C<@>I<file>C<:>I<width>C<:>I<height>C<:>I<start>C<:>I<end>C<:>I<ulimit>C<:>I<llimit> ...
B<flow2rrd>
[B<--config=>I<file>]
B<--cgi>
B<flow2rrd>
B<--version>
B<flow2rrd>
B<--help>
=head1 DESCRIPTION
B<OSSP flow2rrd> is a companion tool to the B<Flow-Tools> toolkit for
storing I<NetFlow> network traffic data in an accumulating fixed-size
B<RRDTool> I<Round-Robin-Database> (RRD) for visualization purposes.
The B<Flow-Tools>' B<flow-capture> command is a I<NetFlow> data
collector which stores received network I<flow> data. B<OSSP flow2rrd>
reads these I<flow> data and stores it into a backend RRD according to
pre-configured hosts, targets and services.
B<OSSP flow2rrd> can then generate host/target and target/service graphs
from the accumulated network traffic data. To support easy on-demand
graph generation and displaying, B<OSSP flow2rrd> can be also called
from a Web server through CGI to render a small two-layer Web user
interface showing graphs of all stored data and allowing a single
graph to be displayed with arbitrary size, time-range and data-range
adjustments.
=head1 OPTIONS
=over 4
=item B<-f>|B<--config> I<file>
Specifies the path to the F<flow2rrd.cfg> configuration file.
See B<CONFIGURATION> section below for details on the
content of the configuration file.
=item B<-s>|B<--store>
Enable the I<data storage operation>. The B<Flow-Tools>' I<flow> data is
expected on F<stdin> with time-ordered records and with the time of the
first record to be higher than the time of the last record from last
B<--store> operation was. This is a constraint from the backend RRD.
=item B<-g>|B<--graph>
Enable the I<graph generation operation>. On the
command line one or more arguments of the form
I<host>[C<:>I<target>]C<@>I<file>C<:>I<width>C<:>I<height>C<:>I<start>C<
:>I<end>C<:>I<ulimit>C<:>I<llimit> are expected, each specifying the
content and output format for a particular graph. Actually, this
operation is intended to be used implicitly under the I<CGI operation>
(see below), but for debugging and manual post-processing reasons (for
instance to generate graphs for importing into B<Cacti> or similar RRD
based tools) is can be used from the command line, too.
The I<host> and I<target> syntax parts have to be strings directly
corresponding to the B<Host> and B<Target> directives in the
configuration file. Specifying just I<host> renders a host/target graph,
specifying I<host> and I<target> renders a target/service graph.
The I<file> syntax part is just the filename where the graph image
is written to. If it ends with the extension "C<.png>", the image is
generated in PNG format. Else, a GIF format image is generated.
The I<width> and I<height> syntax parts are the X and Y sizes of the
graph canvas in the generated image. It is I<not> the size of the image
as a whole because of surrounding titles, annotations, etc. Reasonable
specifications are "C<400:100>" or "C<800:200>".
The I<start> and I<end> syntax parts are the start and end times
(X axis) of the graph. The values effectively are in seconds
since Unix epoch (01-01-1970), but can be also specified as
abbreviated [-+]I<number>[C<smhdwMy>] (e.g. "C<48h>") or as absolute
I<dd>-I<Mmm>-I<yyyy> (e.g. "C<24-Dec-2004>") times. Additionally, the
time can be relative to each others and to the current time. Finally,
"C<now>" specifies the current time. Reasonable specification is
"C<-48h:now>".
The I<ulimit> and I<llimit> syntax parts are the upper and lower (Y
axis) limits of the graph. The values effectively are in Bit/s, but can
be also specified as abbreviated [-+]I<number>[C<KMGT>]. Keep in mind
that usually the upper limit has to be positive and the lower limit
negative. Specifying a limit as "C<0>" means auto-scaling. Reasonable
specifications are "C<0:0>" and "C<2M:-500K>".
=item B<-c>|B<--cgi>
Enable the I<CGI operation>. This option is automatically enabled if
the environment variable C<GATEWAY_INTERFACE> is set to the value
"C<CGI/1.1>".
=item B<-v>|B<--version>
Print the B<OSSP flow2rrd> program version.
=item B<-h>|B<--help>
Print a short command line usage.
=back
=head1 CONFIGURATION
B<OSSP flow2rrd> is configured with a configuration file
F<flow2rrd.cfg> (see also option B<--config> above)
with a syntax generated by the following grammar:
<config> ::= <seq-global>
<seq-global> ::= ( <dir-database> |
<dir-protocol> |
<dir-service> |
<dir-host> |
<dir-colors> )+
<dir-database> ::= "Database" <path> "{" <seq-database> "}" ";"
<dir-protocol> ::= "Protocol" <name> <number> ";"
<dir-service> ::= "Service" <name> (<name>.":".(<number>|"*"))+ ";"
<dir-host> ::= "Host" <hostname> "{" "}" <seq-host> ";"
<dir-colors> ::= "Colors" <name> <color>+ ";"
<seq-database> ::= <dir-stepping> | <dir-storage>
<dir-stepping> ::= "Stepping" <time> ";"
<dir-storage> ::= "Storage" (<time>:<time>)+ ";"
<seq-host> ::= <dir-target>+
<dir-target> ::= "Target" <name> "{" <seq-target> "}" ";"
<seq-target> ::= (<dir-network> | <dir-service>)+
<dir-network> ::= "Network" <network>+ ";"
<dir-service> ::= "Service" <name>+ ";"
<path> ::= /(/?[^/]+|/[^/]*)+/
<name> ::= /[a-zA-Z][a-zA-Z0-9_]*/
<number> ::= /[0-9]+/
<hostname> ::= /[^.]+(\.[^.]+)*/
<network> ::= /^\d+\.\d+\.\d+\.\d+(/\d+)?$/
An example configuration can be seen below in section B<EXAMPLE>.
=head1 EXAMPLE
# Round-Robin Database
Database /var/tmp/flow2rrd.rrd;
# Protocol Definitions
Protocol icmp 1;
Protocol tcp 6;
Protocol udp 17;
Protocol vrrp 112;
# Service Definitions
Service icmp icmp:*;
Service vrrp vrrp:*;
Service ftp tcp:20 tcp:21;
Service ssh tcp:22;
Service smtp tcp:25;
Service dns udp:53 tcp:53;
Service ntp udp:123 tcp:123;
Service radius udp:1645 udp:1646 udp:1812 udp:1813;
# Host Definitions
Host host.example.com {
Target host.example.com {
Network 192.168.0.1/32;
Service icmp vrrp dns ntp ssh smtp;
};
Target service1.engelschall.com {
Network 192.168.0.2/32 192.168.0.3/32;
Service dns smtp;
};
Target service1.engelschall.com {
Network 192.168.0.2/32 192.168.0.3/32;
Service ftp radius;
};
};
=head1 SEE ALSO
B<Flow-Toolkit> E<lt>http://www.splintered.net/sw/flow-tools/E<gt>,
flow-capture(1), B<RRDTool> E<lt>http://www.rrdtool.org/E<gt>, rrdtool(1).
=head1 HISTORY
The B<OSSP flow2rrd> tool was designed and implemented in December 2004
by I<Ralf S. Engelschall> E<lt>rse@engelschall.comE<gt> for the B<OSSP>
project. It was prompted by the need for having accurate and flexible
host network traffic statistics.
=cut
