sa-heatu(1)							   User Commands						       sa-heatu(1)

NAME

       sa-heatu - Spamasassin Heuristic Email Address Tracker Utility

SYNOPSIS

	 sa-heatu [options] [dbfile [timestamp-file]]

DESCRIPTION

       Check or clean a SpamAssassin auto-whitelist (AWL) database file.

       The Auto-WhiteList (AWL) feature in Spamassassing tracks scores from messages previously received and adjusts the message score, either by
       boosting messages from senders who send ham or penalizing senders who have sent spam previously. This not only treats some senders as if
       they were whitelisted but also treats spammers as if they were blacklisted. To enable AWL in spamassassin, read dcoumentation:

	   perldoc Mail::SpamAssassin::Conf

       This is an enhanced version of the original AWL tool. The AWL database can be examined and pruned; single email entries can be removed.
       This is useful when a spammer sends one or more ham messages before sending spam.

       Without special options, the program generates a summary of the database (see FILES):

	   $ sa-heatu -D -n /var/spool/spamassassin/auto-whitelist

	      0 entries removed.
	      0 entries would be expired.
	      0 timestamps would be added.
	      0 timestamps would be updated.

	    308 entries input.
	    308 entries output = input - expired - removed.

       With option --verbose it generates output:

	    AVG   TOTSCORE COUNT  EMAIL IPBASE

       AVG is the average score; TOTSCORE is the total score of all mails seen so far; COUNT is the number of messages seen from that sender;
       EMAIL is the sender's email address, and IPBASE is the AWL base IP address.

       AWL base IP address is a way to identify the sender's IP address they frequently send from, in an approximate way, but remaining hard for
       spammers to spoof. The algorithm is as follows:

	   - Take the last Received header that contains a public IP address;
	     namely one which is not in private, unrouted IP space.

	   - Chop off the last two octets, assuming that the user may be in
	     an ISP's dynamic address pool.

       Negative values indicate senders of ham:

	   average    total count
	      6.8	6.8   1   support@midphase.com			   72.26
	     -8.1     -16.2   2   users-return-@spamassassin.apache.org    98.109
	      1.4      15.9  11   partners@us.cyberoam.com		   38.105
	     13.9      13.9   1   obdg@borgard.com			   89.185

OPTIONS

       -D, --DONTupdatetimestamps
	   No timestamps processing is done. Alias for --noTimestamps.

       -e, --expireOlderThan NUMBER
	   Expire entries older than NUMBER of days.

       -f, --firstTimes
	   Use this for the first run to avoid reading timestamps.

       -h, --help
	   Display short help.

       -n, --noTimestamps
	   No timestamps processing.

       -p, --prune NUMBER
	   Clean out infrequently-used AWL entries. The NUMBER can be used to select the threshold at which entries are kept or deleted. Value 1
	   means that entries seen once are deleted.

       -q, --quiet
	   Be quiet.

       -r, --remove EMAIL
	   Remove EMAIL from database.

       -s, --showUpdates
	   Output entries updated or added or removed, in addition to the summary.

       -v, --verbose
	   Display more information. Note that this may display lot of information from the database.

EXAMPLES

       To see valid senders:

	  sa-heatu --verbose -D | sort -n | head -n 20

       To see top spammers:

	  sa-heatu --verbose -D | sort -n | tail -n 20

       To display single record:

	   sa-heatu --verbose -n | grep -i foo@example.com

       To remove of foo@example.com entry:

	   $ sa-heatu -n --remove foo@example.com

	   Using $HOME/.spamassassin/auto-whitelist

	   average    total count found
	   34.5      34.5   1	  foo@example.com 41.202

	       1 deleted.
	     259 keys with 1 entry.
	     658 keys with 2 entries.
	    1675 entries.

       To shrink the database considerably by removing entries that only have one hit:

	   sa-heatu --prune

       Average total count email address ip network address last time updated: Note: the date and time stamp is the time sa-heatu was run, not the
       time the email was received:

	  sa-heatu --verbose -D | sort -n | head -5

ENVIRONMENT

       None.

FILES

       $HOME/.spamassassin
	   The default working directory of program where dbfile etc. are expected.

	   If dbfile is not given the "$HOME/.spamassassin/auto-whitelist" is used. See also option auto_whitelist_path in Spamassasin Perl module
	   Mail::SpamAssassin::Plugin::AWL which typically points to "/var/spool/spamassassin/auto-whitelist".

SEE ALSO

       spamassassin(1) Mail::SpamAssassin::Plugin::AWL(3p)

STANDARDS

       http://wiki.apache.org/spamassassin/AutoWhitelist

AVAILABILITY

       See STANDARDS for download link.

       The original version this program is based on is at http://svn.apache.org/repos/asf/spamassassin/branches/3.2/tools/check_whitelist

AUTHORS

       Program was written by Dennis G German <DGermansa@Real-world-Systems.com>

       This manual page was written by Jari Aalto <jari.aalto@cante.net>.  Released under license GNU GPL version 2 or (at your option) any later
       version. For more information about license, visit <http://www.gnu.org/copyleft/gpl.html>.

sa-heatu							    2011-01-11							       sa-heatu(1)