Net::Connection::Sniffer::Report -- network profiling reports
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 };
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.
$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
$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: <!--#exec cmd="./nc.sniffer.coalesce.cgi" -->
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 2006 - 2013, 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.
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.