####
# Policy Daemon v1.55
#######################

  Policyd is an anti-spam plugin for Postfix (written in C) that
  does Greylisting, Sender-(envelope,  SASL or  host / ip)-based
  throttling (on messages and /or volume per defined time unit),
  Spamtrap monitoring / blacklisting and HELO auto blacklisting.



###
# Greylisting
###############

  Greylisting   is a  concept that originated  from  Evan Harris
  which is described in  better detail at http://greylisting.org
  Greylisting is a new method of blocking significant amounts of
  spam at  the mailserver  level, but without resorting to heavy
  weight statistical analysis  or other  heuristical (and  error 
  prone)  approaches.  Consequently,  implementations are fairly
  lightweight,   and  may  even   decrease  network  traffic and
  processor load on your mailserver.

  Greylisting  relies on the fact that most  spam sources do not
  behave  in the same way as "normal"  mail systems. Although it
  is currently very effective by itself,  it will  perform  best
  when  it  is  used  in  conjunction  with  other forms of spam
  prevention. 



###
# Sender Throttling 
#####################

  Sender throttling module allows quota enforcement.  Currently
  you may throttle based on amount of mails and total mail size
  send over a given peroid of time which you define.

  Eg: You  can enforce that camis@mweb.co.za does not send more
  than 1000 mails or 1gig of mail (whichever limit is hit first)
  in say a 5 minute  peroid.
  
  There are 3 possible sender throttling methods:

  1) Throttle by (envelope) From address
  2) Throttle by SASL username
  3) Throttle by IP address

  Upon the first time a sender sends a mail through the sender
  throttling module, if they do not exist in the database, the
  module will grab the configuration defaults from policyd.conf
  and those values will be inserted into the datbase. You can
  at a later stage (if you wish) increase those limits by changing
  the values in MySQL. If you wish to create users immediately
  with higher values, you can do the following:

INSERT INTO throttle (_from,_count_max,_quota_max,_time_limit,_mail_size)
 VALUES ('SASL_username',    # from address, SASL username or ip address
          50,                # maximum messages per time unit
          250000000,         # size in bytes (250 megs)
          86400,             # time unit in seconds (1 day)
          10240000);         # maximum message size (10 meg) 

  If you enable throttling by SASL and a client connects to
  Postfix without SASL info, by default Policyd will automatically
  use the MAIL FROM: address so nothing breaks.

  

##
# Spamtrap
############

  The spamtrap module should be very effective, especially in
  really large environments. Previously baited spamtraps would
  require that the mail actually enters the network and gets
  delivered into a mailbox. Any attempted deliveries to any of
  the spamtrap addresses will cause that host/netblock to be
  blacklisted for N amount of hours. Using the spamtrap module
  the host gets blacklisted without having to accept or transfer
  any mail so resources are kept to a minimum.

  Spamtrap format:
  
    INSERT INTO spamtrap (_rcpt,_active) VALUES ('spam@trap.com', 1);
  
  1=active
  0=inactive (strictly for production purposes/testing) 


##
# Blacklist Helo
#################

  The blacklist helo module allows you to blacklist hosts or
  netblocks (c-class) who use HELO and attempt to identify
  themselves using your own hostname/ip address. This will allow
  you to quickly build up a list of known spammer networks.
  This module is effective because its completely automated
  and can be used to permanently ban networks even if they
  stop identifying themselves with your hostnames at a later
  stage.

  INSERT INTO blacklist_helo (_helo) VALUES ('192.168.0.2');
  INSERT INTO blacklist_helo (_helo) VALUES ('[192.168.0.2]');
  INSERT INTO blacklist_helo (_helo) VALUES ('localhost.machine.com');
  INSERT INTO blacklist_helo (_helo) VALUES ('localhost');
  
  In order for this to work properly. You want to INSERT the
  hostname of your machine, your MX hostname, your MX ip address
  and the IP address of your machine (this includes virtual ips
  that reside on your switch)

  NO REMOTE HOST SHOULD IDENTIFY THEMSELVES WITH YOUR MACHINES
  INFORMATION!
  


###
# Compile / Install
#####################

  # cd policy-<VERSION>
  # make build
  # make install

  Create a crontab entry to run the cleanup script:

  # crontab -e

  0 * * * * /usr/local/policyd/cleanup -c /usr/local/policyd/policyd.conf

  questions / comments / ideas etc can goto:
  cami@mweb.co.za



###
# Usage
#########


  Usage: /path/to/policyd -c /path/to/policyd.conf

  Thats pretty much it, all configuration options are
  read out of the configuration file. A standard/demo
  configuration file is included, simply edit as is needed.


	 
	 
###
# Postfix 2.1
###############

  You need Postfix 2.1 or higher in order to use the
  policy service..

  The changes below must be made to main.cf
  
  smtpd_recipient_restrictions =
  ..
    reject_unauth_destination
    reject_unlisted_recipient
    check_policy_service inet:127.0.0.1:10031
  ..




###
# MySQL v4/v3
############

  This code has only been tested on MySQL v4.xx (recommended) and v3.xx
  Included is a file called 'DATABASE.mysql' which you can use to create
  all the nessasary tables.

  # mysql -p < DATABASE.mysql
  

  Permissions for policyd:
  
  NB!! The information provided below should match that of your Configuration

  Example for 1 host:
  
    GRANT ALL ON policyd.* TO postfix@127.0.0.1 IDENTIFIED by 'p0stf1x';

  Example for a netblock:
 
    GRANT ALL ON policyd.* TO postfix@"192.168.0.0/255.255.255.0" IDENTIFIED
    by 'p0stf1x';



##
# Whitelist
#############

  Included is a file called 'WHITELIST.sql'. Import it into mysql by doing:
  mysql policyd < WHITELIST.sql -p 
    
  Whitelisting format:

    INSERT INTO whitelist (_whitelist,_description) VALUES ('127.%.%.%','# localhost');



##
#  Blacklist
##############
    
  Blacklisting format:
    
    INSERT INTO blacklist (_blacklist,_description) VALUES ('222.76.50.%','# spam');
  
  As you can see in the above example, if you want to white or blacklist a
  subnet (whether it is an A B or C class), simply fill % in the other octet(s).




##
# Greylist Opt-in / Opt-out
#############################

  Certain accounts / spamtraps / users do not want greylisting.
  Opt-in/out can be enabled in policyd.conf

  _priority is an indication of which entry has the highest preference.

  So for example, if you want only ONE user to be subjected to greylisting
  for the domain mweb.co.za:

  1 == Opt-in
  0 == Opt-out

  INSERT INTO policy (_rcpt,_optin,_priority) VALUES ('@mweb.co.za', 0, 10);
  ^^ above mweb.co.za is by default opted out.

  INSERT INTO policy (_rcpt,_optin,_priority) VALUES ('cami@mweb.co.za', 1, 50);
  ^^ above camis@mweb.co.za has a higher priority therefore will override the
     first rule

  This allows for mixed and matched configurations. So another example, if
  you want everyone for the domain to be subjected to greylisting EXCEPT
  for camis@mweb.co.za:
  
  INSERT INTO policy (_rcpt,_optin,_priority) VALUES ('@mweb.co.za', 1, 10);
  ^^ above mweb.co.za is by default opted out.

  INSERT INTO policy (_rcpt,_optin,_priority) VALUES ('cami@mweb.co.za', 0, 50);
  ^^ above camis@mweb.co.za has a higher priority therefore will override the
     first rule



###
# Logging format
##################
  
  # rcpt
  Dec  2 20:40:05 localhost policyd: rcpt=8712, greylist=update, host=192.168.0.2
    (localhost), from=cami@mweb.co.za, to=camis@mweb.co.za

  rcpt is the number of times that Postfix has connected to policyd and issued
  a valid Policy Daemon service request.

  # throttling
  throttle=new          <- first mail from a sender
  throttle=update       <- update mail quota
  throttle=abuse        <- user limit has been reached
  throttle=clear        <- user time has expired

  # greylisting
  greylist=new          <- 1st attempt to delivery mail to a user
  greylist=new_train    <- 1st attempt to delivery mail to a user (training mode)
  greylist=update       <- 2nd or more mail delivery attempts
  greylist=update_train <- 2nd or more mail delivery attempts (training mode)
  greylist=awl		<- autowhitelist enabled & triggered
  greylist=pass         <- mysql has failed, but failover mode is enabled
  greylist=fail         <- mysql has failed, failover mode is disabled
  greylist=abuse        <- 2 or more mail delivery attempts
                           within 5 minutes of first attempt
  Example:
   Dec  2 20:40:05 localhost policyd: greylist=update, host=192.168.0.2
     (localhost), from=cami@mweb.co.za, to=camis@mweb.co.za 

  # spamtrap / other
  type=spamtrap         <- delivery attempt to a spamtrap address
  type=whitelist        <- whitelisted host/netblock
  type=blacklist        <- blacklisted host/netblock
  type=blacklist_helo   <- host caught using forged HELO

  
  

#######
# EOF #
#######
