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)