NAME

Net::Connection::Sniffer::Report -- network profiling reports

SYNOPSIS

            

              
              
 use Net::Connection::Sniffer::Report qw(
read_stf
by_cidr24
by_name
report
presync
sync
chkcache
get_lock
chk_wconf
rqst_dump
web_report
my_time
dyn_bind
 };
            
          

DESCRIPTION

Net::Connection::Sniffer::Report consolidates the dump file produced by Net::Connection::Sniffer.

            

              
              
($stats,$head) = read_stf($filepathname);
($byc24,$rate,$bw) = by_cidr24($stats);
($byname,$rate,$bw) = by_name($stats,$byc24);
 $rv = report(*HANDLE,$file,$type);
 $rv = presync($filepathname);
 $rv = sync($filepathname,$oldtime,$timeout);
 $rv = chkcache($filepathname,$age);
($lock,$file) = get_lock($filepathname,$timeout,$umask);
 $rv = chk_wconf($conf);
 $rv = rqst_dump($sin,$file,$age,$updto);
 web_report($wconf);
 $timestring = my_time($epoch_seconds);
 $port = dyn_bind($sock,$iaddr);
            
          

• ($stats,$head) = read_stf($filepathname);

  Read the Net::Connection::Sniffer status file and return a reference to its contents.

  
              
  
                
                
  input:  file path
  returns:        undef or empty array on failure
          [$@ is set with error]
    or scalar
  reference to status hash
    or array
  (status ref, $header)
              
            

  Where the $header content is extracted from the Net::Connection::Sniffer status file.

• ($byc24,$rate,$bw) = by_cidr24($stats);

  Return a reference to the composite of the status hash with usage grouped by cidr/24

  
              
  
                
                
   input: reference to $stats
   returns:       $composite,     # reference to composite hash
          $rate,          # calculated queries per hour
          $bw             # calculated bytes per hour
                   
   $composite = {
      number  => {             # number is for administrative use only
  R       => 12345,    # composite queries / hour
  W       => 45678,    # composite bytes / hour
  A       => ['ip1','ip2','...'], # ip addr's in cidr/24
  E       => 12345,    # last update timestamp
      },
      another number => {      and so on...
              
            

• ($byname,$rate,$bw) = by_name($stats,$byc24);

  Further groups the composite statistics by primary sub domains.

  
              
  
                
                
   input: reference to statistics hash,
          reference to cidr24 grouping
   returns:       $byname,        # reference to composite hash
          $rate,          # calculated queries per hour
          $bw             # calculated bytes per hour
   $byname = {
      rev_subdomain => {               # text for administrative use
  R       => 12345,    # composite queries / hour
  W       => 45678,    # composite bytes / hour
  A       => ['ip1','ip2','... # and so on...
  E       => 12345,    # last update timestamp
     },
     another rev subdomain => {        and so on...
              
            

• $rv = report(*HANDLE,$file,$type);

  Generate a statistics usage report ordered from highest to lowest bandwidth usage.

  Two types of reports are created:

  
              
  
                
                
  1) grouped by cidr24 [default], $type = false
  2) grouped by sub domain, $type = true
  input:  *HANDLE,        # file or *STDOUT
  $file           # path/to/statistics_file
  $type,          # true/false
  returns:        returns false on success
  or the error
  prints: to the file handle
              
            

• $rv = presync($filepathname);

  Wait up to one second for the file to be older than now.

  
              
  
                
                
  input:  $fpn,   # path to file
  returns:        $ctime  # file ctime
     or   0 if the file does not yet exist
     or   undef on error (ctime in future)
              
            

• $rv = sync($filepathname,$oldtime,$timeout);

  Wait for file ctime to update, fail on timeout.

  
              
  
                
                
  input:  $fpn,   # path to file
  $old,   # original ctime or
          # 0 if the file will be created
  $to,    # timeout in seconds
          # [default 30 seconds]
  returns:        $ctime  # file ctime
     or   undef on failure
  Sets $@ on timeout;
              
            

  Sets $@ on timeout. If the file is not initially found, sync will wait for the timeout period if the directory is present and readable.

• $rv = chkcache($filepathname,$age);

  Check if a file is older than 'age'

  
              
  
                
                
  input:  file    # path to file
  age     # maximum age in seconds
          # [default = 300 seconds]
  return: ctime if not too old
  undef if too old or missing
              
            

• ($lock,$file)=get_lock($filepathname,$timeout,$umask);

  Return an exclusive file handle.

  
              
  
                
                
  input:  $file,          # path to file
  $to,            # timeout in seconds
                  # [default 15 seconds]
  $umask          # [default 0117]
  returns:        ($lock,$file)   # handles
     or   () on error
  Sets $@ on error.
  NOTE: the file path must be prechecked!
              
            

  Remember to close both the FILE and the LOCKFILE.

• $rv = chk_wconf($conf);

  Check the syntax and content of the web configuration hash.

  
              
  
                
                
  input:  hash reference
  returns:        false on success or error text
              
            

• $rv = rqst_dump($sin,$file,$age,$updto);

  Request a stats dump from the daemon

  
              
  
                
                
  input:  sockaddr_in,    # address dump rqst host
  path/to/statsfile,
  age,            # in seconds i.e. 300
  update timeout
  returns:        false on success or error text
              
            

  If $sin is false, not dump is performed

  If age if false, dump is requested unconditionally

• web_report($wconf);

  Print a report to STDOUT. Takes the type of report from the first argument.

  
              
  
                
                
  usage: <!--#exec cmd="./nc.sniffer.cgi 0" -->
    or     <!--#exec cmd="./nc.sniffer.cgi 1" -->
              
            

  where an argument of "0" produces a report ordered by /24 by usage and an argument of "1" produces a report ordered by subdomain by usage.

  
              
  
                
                
  input:  config pointer
  returns:        prints to STDOUT
              
            

  where $wconf = {

  
              
  
                
                
   # location of statistics file
   # [REQUIRED]
   #
  stats   => '/var/run/nc.sniffer/nc.sniffer.stats',
   # location of web cache file, this must exist
   # and be writable by the web daemon
   # [RECOMMENDED]
   #
  cache   => './tmp/sniffer.cache',
   # statstistics update timeout
   # [OPTIONAL] default 15 seconds
   #
  updto   => 15,
   # cache or stats (if cache not activated above)
   # refresh every nnn seconds
   # default is 300 seconds
   # [OPTIONAL]
   #
  refresh => 300,
   # update host:port
   #
   # format:
   #      port
   #   or
   #      host:port
   #   or
   #      ipaddr:port
   #
   # host defaults to 'localhost', 127.0.0.1
   # [REQUIRED]
   #
  update  => '127.0.0.1:10004',
   };
              
            

• $timestring = my_time($epoch_seconds);

  Convert seconds since the epoch into a formated local time string of the form:

  
              
  
                
                
  Month-text day hh::mm::ss
  input:  seconds since the epoch
  returns:        local time string
              
            

• $port = dyn_bind($sock,$iaddr);

  Attempt to bind a socket to the IP address and the first available dynamic assigned port, in the range 49152 through 65535. Fails after 100 attempts

  
              
  
                
                
  input:  socket
  IP addr as returned by inet_aton
  returns:        port number or undef
              
            

EXPORT_OK

            

              
              
read_stf
by_cidr24
by_name
report
presync
sync
chkcache
get_lock
chk_wconf
rqst_dump
web_report
my_time
dyn_bind
            
          

COPYRIGHT

Copyright 2006, Michael Robinton <michael@bizsystems.com>

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License (except as noted otherwise in individuals sub modules) 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.

AUTHOR

Michael Robinton <michael@bizsystems.com>