OSSP CVS Repository

ossp - Check-in [4911]
Not logged in 		[Honeypot]  [Browse]  [Home]  [Login]  [Reports] 
[Search]  [Ticket]  [Timeline] 
  [Patchset]  [Tagging/Branching] 

Check-in Number: 4911
Date: 2004-Dec-26 13:32:38 (local)
2004-Dec-26 12:32:38 (UTC)
User:rse
Branch:
Comment: The next step in providing some documentation
Tickets:
Inspections:
Files:
ossp-pkg/flow2rrd/flow2rrd.pl      1.4 -> 1.5     4 inserted, 7 deleted
ossp-pkg/flow2rrd/flow2rrd.pod      1.1 -> 1.2     185 inserted, 3 deleted
ossp-pkg/flow2rrd/flow2rrd.pl 1.4 -> 1.5 

--- flow2rrd.pl  2004/12/23 21:37:19     1.4
+++ flow2rrd.pl  2004/12/26 12:32:38     1.5
@@ -1,6 +1,6 @@
 #!/usr/opkg/bin/perl
 ##
-##  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/>
 ##
@@ -60,7 +60,6 @@
 my $opt = {
     -help     => 0,
     -version  => 0,
-    -verbose  => 0,
     -config   => 'flow2rrd.cfg',
     -store    => 0,
     -graph    => 0,
@@ -71,8 +70,7 @@
 Getopt::Long::Configure("bundling");
 my %getopt_spec = (
     'h|help'     => \$opt->{-help},
-    'V|version'  => \$opt->{-version},
-    'v|verbose'  => \$opt->{-verbose},
+    'v|version'  => \$opt->{-version},
     'c|config=s' => \$opt->{-config},
     's|store'    => \$opt->{-store},
     'g|graph'    => \$opt->{-graph},
@@ -84,8 +82,7 @@
     print "usage: $my->{-progname} [<options>] <hostname>\n" .
           "available options are:\n" .
           "  -h,--help              print out this usage page\n" .
-          "  -v,--verbose           enable verbose run-time mode\n" .
-          "  -V,--version           print program version\n" .
+          "  -v,--version           print program version\n" .
           "  -c,--config FILE       read this configuration file only\n" .
           "  -s,--store             store NetFlow values into RRD\n" .
           "  -g,--graph             produce RRD graphs\n" .
@@ -233,7 +230,7 @@
     my $ctx = &data_init($cfg);
 
     #   scan flow-tools stream on STDIN for NetFlow records
-    Cflow::verbose(1);
+    Cflow::verbose(0);
     Cflow::find(sub { &foreach_record($cfg, $ctx) }, "-");
     sub foreach_record {
         my ($cfg, $ctx) = @_;

ossp-pkg/flow2rrd/flow2rrd.pod 1.1 -> 1.2 

--- 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

CVSTrac 2.0.1