NAME

Mail::SpamCannibal::ScriptSupport - A collection of script helpers

SYNOPSIS

  use Mail::SpamCannibal::ScriptSupport qw(
	DO
	doINCLUDE
	SerialEntry
	TarpitEntry
	DNSBL_Entry
	id
	question
	revIP
	query
	dns_udpsend
	dns_udpresp
	dns_ans
	dns_ns
	dns_ptr
	rlook_send
	rlook_rcv
	zone_def
	valid127
	validIP
	zap_one
	zap_pair
	job_died
	dbjob_chk
	dbjob_kill
	dbjob_recover
	unpack_contrib
	lookupIP
	list2NetAddr
	matchNetAddr
	BLcheck
	checkclct
	dumpIPs
	BLpreen
	mailcheck
	abuse_host
	is_GENERIC
	block4zonedump
  );

FUNCTIONS

$rv = DO($file,$nowarnings);
$rv = doINCLUDE($file,$nowarnings);
$packedIPaddr = SerialEntry()
$packedIPaddr = TarpitEntry();
$packedIPaddr = DNSBL_Entry();
$unique = id($seed);
$querybuf = question($name,$type);
$rev = revIP($ip);
$response = query(\$buffer,$timeout);
$socket = dns_udpsend(\$buffer,$timeout);
$response = dns_udpresp($socket,$timeout);
($aptr,$tptr,$auth_zone) = dns_ans(\$buffer);
$nsptr = dns_ns(\$buffer);
$hostname = dns_ptr(\$buffer);
@hosts = dns_ptr(\$buffer);
$socket = rlook_send($IP,$timeout);
$hostname = rlook_rcv($socket,$timeout);
($expire,$error,$dnresp,$timeout)=zone_def($zone,\%dnsbl);
$dotquad = valid127($dotquad);
$dotquad = validIP($dotquad);
$rv = job_died(\%jobstatus,$directory);
$rv = dbjob_chk(\%default_config);
dbjob_kill(\%default_config,$graceperiod);
dbjob_recover(\%default_config);
($respip,$err,$blrsp,$exp,$zon)=unpack_contrib($record);
($which,$text)=lookupIP(\%config,$dotquadIP,$sockpath,$is_network);
$rv=list2NetAddr(\@inlist,\@NAobject);
$rv = matchNetAddr($ip,\@NAobject);
$rv = BLcheck(\%DNSBL,\%default);
$hashref = checkclct($DNSBL);
$rv = dumpIPs($DNSBL, $allipsHASHptr);
$rv = BLpreen(\%DNSBL,\%default);
@err=mailcheck($fh,\%MAILFILTER,\%DNSBL,\%default,\@NAignor,\$spamsource)
$rv=zap_one($tool,$netaddr,$db,$verbose,$comment);
zap_pair($tool,$netaddr,$pri,$sec,$debug,$verbose,$comment);
$rv = is_GENERIC($conf->{GENERIC},@hostnames);
block4zonedump($environment);

METHODS

$object = new Mail::Spamcannibal::ScriptSupport;
$rv = $object->dns2rblz($line);
$firstline = $object->rbldns_combined($type);
$textline = $object->rbldns_compress($textline);
$lastline = $object->rbldnst_done();
$lastline = $object->rbldns_done();
$last_combined = rbldns_address();

DESCRIPTION

Mail::SpamCannibal::ScriptSupport provides a collection of support utilities for sc_BLcheck, sc_BLpreen, sc_mailfilter, sc_admin, sc_session, and cannibal.cgi.

$rv = DO($file,$nowarnings);

Imported from File::SafeDO for legacy applications.

This is a fancy 'do file'. It first checks that the file exists and is readable, then does a 'do file' to pull the variables and subroutines into the current name space.
```
  input:	file/path/name
  returns:	last value in file
	    or	undef on error
	    prints warning
```
$rv = doINCLUDE($file,$nowarnings);

Imported from File::SafeDO for legacy applications.

Similar to above but supports INCLUDE keys.

See: File::SafeDO
$packedIPaddr = SerialEntry();

Returns the packed internet address equivalent to inet_aton('127.0.0.0'). Make sure and use the parens at the end of the function.
$packedIPaddr = TarpitEntry();

Returns the packed internet address equivalent to inet_aton('127.0.0.2'). Make sure and use the parens at the end of the function.
$packedIPaddr = DNSBL_Entry();

Returns the packed internet address equivalent to inet_aton('127.0.0.3'). Make sure and use the parens at the end of the function.
($expire,$error,$dnresp,$timeout)=zone_def($zone,\%dnsbl);

Parse the zone information and return either the default values or the overides from the config file.
```
  Defaults:
	$expire	= '7d' 	# in seconds
	$error	= 'Blacklisted by: $zone'
	$dnresp	= inet_aton('127.0.0.3')
	$timeout  undef
```
NOTE: if the respone code found in the config file is not in the 127./8 block or is less than 127.0.0.3, $dnresp will be set to the default value.
$dotquad = valid127($dotquad);

This function checks an IP address in dot quad notation to see if it is in the range 127.0.0.3 to 127.255.255.255. It returns 127.0.0.3 if the IP address is outside that range.
```
input:	dot quad ip address
returns:	input or 127.0.0.3
```
$dotquad = validIP($dotquad);

This function inspects an IP address and returns it if is valid.
```
input:	dot quad address
returns:	dot quad address or undef
```
$rv=zap_one($tool,$netaddr,$db,$verbose,$comment);

Helper function to remove a record from one database. It conditionally removes the record from $db. No removal is performed if $debug is true, it is just "commented". Action or proposed action is commented if $debug or $verbose is true. $comment is appended to the standard "remove" message if $comment exists.
```
  input:	$tool,	  # ref to Tools
		$netaddr, # IP to remove
		$db,	  # database name
		$debug,	  # mode
		$verbose, # report intensity
		$comment,

  output:	1 on removal, 0 if no record removed
```
zap_pair($tool,$netaddr,$pri,$sec,$debug,$verbose,$comment);

Helper function for BLpreen. It conditionally removes the records for $netaddr from databases $pri and $sec. No removal is performed if $debug is true, it is just "commented". Action or proposed action is commented if $debug or $verbose is true. $comment is appended to the standard "remove" message if $comment exists.
```
  input:	$tool,	  # ref to Tools
		$netaddr, # IP to remove
		$pri,	  # database name
		$sec,	  # database name
		$debug,	  # mode
		$verbose, # report intensity
		$comment,

  output:	false on success, or
		an error message
```
& $rv = job_died(\%jobstatus,$directory);

This function checks for pid files in the $directory. The absolute pid file path is inserted into %jobstatus with a value of it's pid. Tasks that are not running return a pid value of zero (0).
```
  input:	pointer to job status hash,
		pid file directory
  returns:	true if a task is not running
		else false
```
$rv = dbjob_chk(\%default_config);

This function checks if data base tasks have exited abnormally. If an abnormal exit is detected, the file blockedBYwatcher containing the watcher pid is created in the environment directory and the function return false, otherwise it returns true.
```
  input:	pointer to db configuration,
  returns:	true if all known tasks are running
		or exited normally, else returns false
```
dbjob_kill(\%default_config,$graceperiod);

This function kills all db tasks that have registered PID files in the environment directory. These jobs are shutdown, first with a SIG TERM and if they do not respond withing the grace period, a SIG KILL.
```
  input:	pointer to db configuration,
		task shutdown grace period
  returns:	nothing
```
dbjob_recover(\%default_config);

This function destroys and reinstantiates the database environment. The file blockedBYwatcher is removed from the environment directory if it is present.

All DB tasks should be terminated prior to calling this function.

DO NOT call this job for a DB environment that has not been initialized.
```
 usage: if(dbjob_chk(\%default_config) {
	  dbjob_kill(\%default_config,$graceperiod);
	  dbjob_recover(\%default_config);
	... restart db jobs
	}

  input:	pointer to db configuration,
  returns:	nothing
```

($respip,$err,$blrsp,$exp,$zon)=unpack_contrib($record);

Unpack a 'blcontrib' record.

  input:	record from 'blcontrib' database
  output:	netaddr - our response code,
		our error message,
		netaddr - remote response code,
		expire
		dnsbl zone

This undoes pack("a4 x A* x a4 x N x A*",@_);

($which,$text)=lookupIP(\%config,$dotquadIP,$sockpath,$is_network);

This function checks the SpamCannibal databases for the presence of an IP address and returns a text string describing why the IP address is in the SpamCannibal data base or a descriptive not found message.
```
  input: (localhost)
		\%database config,
		dotquad IP address,
		/path/to/fifo,
		0,
	 (or remote host)
		\%database config,
		dotquad IP address,
		hostname:port,
		timeout seconds 

  returns:	which database,
		text string

	which = 0 for evidence
		1 for blcontrib
```
NOTE: the database config hash is the same as returned by Mail::SpamCannibal::SiteConfig

Text error return messages: message, meaning

invalid IP address, says it all not found in system database, not in tarpit db remote data record missing, found in contrib no text no remote data record found, says it all
$rv=list2NetAddr(\@inlist,\@NAobject);

Imported from Net::DNSBL::Utilities for legacy applications

Build of NetAddr object structure from a list of IPv4 addresses or address ranges. This object is passed to matchNetAddr to check if a given IP address is contained in the list.
```
  input:	array reference pointer
		to a list of addresses

  i.e.		11.22.33.44
		11.22.33.0/24
		11.22.33.0/255.255.255.0
		11.22.33.20-11.22.33.46
		11.22.33.20 - 11.22.33.46

  output:	Number of objects created
		or undef on error
```
The NAobject array is filled with NetAddr::IP::Lite object references.
$rv = matchNetAddr($ip,\@NAobject);

Imported from Net::DNSBL::Utilities for legacy applications

Check if an IP address appears in a list of NetAddr objects.
```
  input:	dot quad IP address,
		reference to NetAddr objects
  output:	true if match else false
```
$rv = BLcheck(\%DNSBL,\%default);

This function checks the each IP address found in the 'archive' database {SPMCNBL_DB_ARCHIVE} against the list of DNSBLs found in the "sc_addspam.conf" configuration file. IP addresses which match the acceptance criteria are added to the 'tarpit' database {SPMCNBL_DB_TARPIT} and a corresponding entry is made in the 'blcontrib' database {SPMCNBL_DB_CONTRIB} giving the reason for the addition.
```
  input:	config file hash ref,
		db config hash ref
  output:	false on success, or
		an error message
```
See: config/sc_BlackList.conf.sample for a detailed description of each element in the configuration file. See: scripts/sc_BLcheck.pl for usage and configuration information for the db config hash reference.

This routine will return if it catches a SIGTERM. The longest it will wait is the timeout for a DNS query.
$hashref = checkclct($DNSBL);

Return undef or a hashref for collecting IP's.
```
input:	config file hash ref
output:	IP collection hash ref
```
Used by BLcheck
$rv = dumpIPs($DNSBL, $allipsHASHptr);

Dump the %allips hash in a Data::Dumper compatible format to the file pointed to by 'ALLIPS' in config.
```
  input:	config pointer,
		pointer to ALLIPS hash
  returns:	false on success or error message
```
Used by BLcheck
$rv = BLpreen(\%DNSBL,\%default);

This function validates each IP address found in the 'blcontrib' database {SPMCNBL_DB_CONTRIB} for presence of its original dnsbl zone entry in the configuration file and that the remote dnsbl still has an acceptable 'A' record. IP addresses which fail either of these criteria or for which the remote dnsbl does not respond for the 'expire' interval (see sc_addspam.conf) are removed from the 'tarpit' database {SPMCNBL_DB_TARPIT} as well as the 'blcontrib' database {SPMCNBL_DB_CONTRIB}. 'contrib' items found in the 'evidence' are unconditionally discarded instead of being checked.
```
  input:	config file hash ref,
		db config hash ref
  output:	false on success, or
		an error message
```
See: config/sc_BlackList.conf.sample for a detailed description of each element in the configuration file. See: scripts/sc_BLpreen.pl for usage and configuration information for the db config hash reference.

This routine will return if it catches a SIGTERM. The longest it will wait is the timeout interval for a DNS query.

@err=mailcheck($fh,\%MAILFILTER,\%DNSBL,\%default,\@NAignor,\$spamrcd)

This function extracts the sending mail server address, headers, and message content from an "email message" that may [optionally] be PGP encoded. If an IP address is successfully recovered, it is added to the 'tarpit' database {SPMCNBL_DB_TARPIT} and the headers and message are added to the 'evidence' database {SPMCNBL_DB_EVIDENCE}. See: config/sc_mailfilter.conf.sample for configuration and details on optional settings.

  input:	file handle,
		config hash ptr,
		dnsbl config hash ptr,
		default config hash ptr,
		net object ptr,
		[optional] spam info array pointer 
  output:	empty array on success,
		(verbosity, err msg) on failure
	where verbosity is false on success,
	1,2,3, etc.... on failure

  my %default = (
	dbhome  => $environment,
	dbfile  => [$tarpit],
	txtfile => [$evidence],
	DEBUG   => $DEBUG,
	LIMIT   => $CHAR_SAVE_LIMIT, # characters
	PGPLIM	=> $CHAR_READ_LIMIT,
  );

  [optional] spam info array pointer
  $spamip = ['spam source name or ip','spam headers + message']
  This array will be filled by mail check if it is present

@err=abuse_host($fh,\%MAILFILTER,,\%localvars,\@NAignor)

This function extracts the abuse host name and IP address from the headers passed in as "message text"

  input:	file handle,
		config hash ptr,
		dnsbl config hash ptr,
		$localvars->{dbhome => path to environment},
		net object ptr,

  output:	empty array on success,
		(verbosity, err msg) on failure
	where verbosity is false on success,
	1,2,3, etc.... on failure

		fills %$localvars{
			SPAM	=> read buffer so far,
			shost	=> spam host,
			to	=> abuse host
			hostIP	=> ip address
			ab2	=> [for debug]
		};

$rv = is_GENERIC($conf->{GENERIC},@hostnames)

Check if a list of hostnames are all generic

  input:	hash pointer to 'GENERIC',
		hostname list
  returns:	true is generic
		false is not

block4zonedump($environment);

Checks to see if a dnsbl zonedump is in progress and blocks until the zonedump is complete
```
input:	$environment pointer
returns:	nothing
```
$object = new Mail::Spamcannibal::ScriptSupport;

Returns a reference to a Mail::Spamcannibal::ScriptSupport object
$rv = $object->dns2rblz($line);

Converts DNS bind file lines created by dnsbls to the rbldns format.
```
input:	DNS bind file line
returns:	rbldns file line or ''
```
Note: if the DNS file was dumped in standard format, the returned rbldns lines will be in the standard format also. If the DNS file was created in promiscious mode, the rbldns lines will be in the enhanced format provided by:
```
	djbdns-1.05 rbldns patch

  found at:

	http://www.jms1.net/djbdns/rbldns-patch.html
```
$textline = $object->rbldns_compress($textline);

Compress ip4tset rbldnsd data file lines produced by dns2rblz above to ip4set data format.
```
input:	ip4tset line
returns:	ip4set line
```
$firstline = $object->rbldns_combined($type);

Write the first line of an rbldns combined dataset of type ip4set | ip4tset.
```
  input:	type, one of ip4set or ip4tset
  returns:	dataset statement for ip4set
	    or	undef on error
```
$last_combined = rbldns_address();

Write the generic format address record(s) for the name server within this address. This should be the last record after the ip4set is generated using a starting header generated by rbldns_combined (above).
```
input:	none
returns:	dataset statement + address
```
$lastline = $object->rbldns_done();

Complete the last line of an ip4set dataset conversion.
```
  input:	none
  returns:	remainder of last line
		in the ip4set data file
```
$lastline = $object->rbldnst_done();

Complete the last line of an ip4tset dataset conversion.
```
  input:	none
  returns:	remainder of last line
		in the ip4tset data file
```

DEPENDENCIES

NetAddr::IP::Lite
Net::DNS::Codes
Net::DNS::ToolKit
Net::DNS::ToolKit::RR
Mail::SpamCannibal::GoodPrivacy
Mail::SpamCannibal::BDBclient

EXPORT

none by default

EXPORT_OK

DO
doINCLUDE
SerialEntry
TarpitEntry
DNSBL_Entry
id
question
revIP   
query   
dns_ans 
zone_def
valid127
validIP
zap_one
zap_pair
job_died
dbjob_chk
dbjob_kill
dbjob_recover
unpack_contrib
lookupIP
list2NetAddr
matchNetAddr
BLcheck
checkclct
dumpIPs
BLpreen
mailcheck
abuse_host
is_GENERIC
block4zonedump

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as 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>

	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)