--- flow2rrd.pod 2004/12/23 21:37:19 1.1
+++ flow2rrd.pod 2004/12/26 12:32:38 1.2
@@ -1,5 +1,5 @@
##
-## OSSP flow2rrd -- Store NetFlow Data in Round-Robin Database (RRD)
+## OSSP flow2rrd -- NetFlow to Round-Robin Database (RRD)
## Copyright (c) 2004 Ralf S. Engelschall <rse@engelschall.com>
## Copyright (c) 2004 The OSSP Project <http://www.ossp.org/>
##
@@ -28,15 +28,197 @@
=head1 NAME
-B<OSSP flow2rrd> - Store NetFlow Data in Round-Robin Database (RRD)
+B<OSSP flow2rrd> - NetFlow to Round-Robin Database (RRD)
=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<-c>|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 usually has to be used by a CGI
+wrapper script placed somewhere in the Web server F<cgi-bin> directory:
+
+ #!/bin/sh
+ # I'm /path/to/cgi/flow2rrd.cgi
+ /path/to/bin/flow2rrd --cgi
+
+=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> ";"
+ <dir-protocol> ::= "Protocol" <name> <number> ";"
+ <dir-service> ::= "Service" <name> (<name>.":".(<number>|"*"))+ ";"
+ <dir-host> ::= "Host" <hostname> "{" "}" <seq-host> ";"
+ <dir-colors> ::= "Colors" <name> <color>+ ";"
+ <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 under 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
-flow-capture(1), rrdtool(1).
+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
|
