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
rem_wchk
rqst_dump
web_report
my_time
dyn_bind
xhandle
rem_dump
rem_update
chk_lock
rem_report
 };

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 = rem_wchk($conf);
 $rv = rqst_dump($sin,$file,$age,$updto);
 web_report($wconf);
 $timestring = my_time($epoch_seconds);
 $port = dyn_bind($sock,$netaddr);
 $handle = xhandle($program_string);
 $rv = rem_dump($conf);
 $rv = rem_update($config);
 rem_report($wconf);

($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 = rem_wchk($conf);

Check the remote fetch configuration file.

Note: ignores missing 'update' entry if localhost is not specified for update.


            
              
              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,$netaddr);


            
              
              re-exported from Net::NBsocket

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


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

$handle = xhandle($program_string);

Open a program string for read and return handle.


            
              
              input:  program string
returns:        handle or undef on failure to open

$rv = rem_dump($conf);

Dump and retrieve stats files from remote hosts and localhost if present.


            
              
              input:  hash pointer to config
returns:        true on success

$rv = rem_update($config);

Update the composite stats report


            
              
              input:  hash pointer to config
returns:        true on success

$rv = chk_lock ($lockfile);


            
              
              input:  lockfile name
return: 0       lock released
1       lock expired, 2 min

rem_report($wconf);

Similar to sub 'web_report' above but retrieves and assembles a composite report from multiple hosts running nc.sniffer

HOWTO setup this operation.
```
            
              
              1) read the config section of 
   nc.sniffer.coalesce.cgi.sample
2) read the config section of
   nc.sniffer.dump.pl.sample
            
          
```
On the remote host, install nc.sniffer.dump.pl in an appropriate sandbox account and install an ssh certificate to permit access to the sandbox ssh executable as well as the directory from which to rsync the stats file on that host.

nc.sniffer.dump.pl should be installed mode 755 or as appropriate to be accessed remotely by the ssh -e function.

On the web host, configure nc.sniffer.coalesce.cgi and place the execution cgi string in your web page to produce the report
```
            
              
              usage: 
            
          
```

EXPORT_OK


            
              
              read_stf
by_cidr24
by_name
report
presync
sync
chkcache
get_lock
chk_wconf
rem_wchk
rqst_dump
web_report
my_time
dyn_bind
xhandle
rem_dump
rem_update
chk_lock
rem_report

COPYRIGHT

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>

To install Net::Connection::Sniffer, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Net::Connection::Sniffer

CPAN shell

perl -MCPAN -e shell
install Net::Connection::Sniffer

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)