0.1.12                                                                12/06/2005

                          Policyd-weight documentation


                      1.0 ............ What is policyd-weight
                       1.1 ....... What is policyd-weight not
                       1.2 ........ For who is policyd-weight
                       1.3 ..................... Requirements 
                      
                      2.0 .................. How does it work
                       2.1 ................. How to set it up
                       2.2 .. How to read/understand the logs
                      
                      3.0 ............................ Thanks





1.0 What is policyd-weight

    Policyd-weight is a perl script for postfix to score
    - DNSBLs/RHSBLs
    - HELO argument
    - MAIL FROM: argument
    - Client IP Address
    - DNS client/HELO/FROM entries (A/16 A/24 A/32, PTR/FQDN and Parent Domains
      MX/16 MX/24 MX/32 for their correctness respectively whether they match.

     Most MTAs have checks for this, but unfortunately those checks are
    too restrictive, causing important mails to get rejected. Thus most
    companies are forced to have a rather non restrictive and insecure MTA setup
    to don't lose important mails. Policyd-weight is intented to be used
    straight after the received RCPT TO command. This way neither the
    mail-headers nor the mail-body must be received. This is different from
    other filters as those must parse (and receive) the complete mail.
    With the policyd-weight approach we can safely reject Faked Mails and 
    MTAs that are too much listed in DNSBLs.

    Policyd-weight is able to catch up to 95% of bogus mails BEFORE receiving
    of the complete mail.

    NOTE: new spam-mailers on the internet are not listed in DNSBLs, and if they
          don't fake everything it appears as normal mail. Spam-Assassin or
          amavisd will parse the mail and report it to DNSBLs (if set up this
          way, consult your spam-/virusscanner's manual).



1.1 What is policyd-weight not

    Policyd-weight is NOT a Spam or Virus Filter - as it doesn't parse
    the contents of the mail.

    Policyd-weight is not able to reject Mails bounced or forwarded by correct
    MTAs.
    Example: you have an account at yahoo.com, and a have set forwarding
    to your companie's account. Yahoo.com sends with correct MTAs, and thus
    SPAM received from your yahoo.com account will pass this filter.



1.2 For who is policyd-weight

    For now: for postfix users that receive or relay mail 
    via SMTP (not via POP).
    For peoples that receive loads of E-Mails catched by Spam-Assassin or
    Amavisd (I'm talking about 300+/day). For peoples that want to reduce 
    bandwidth-usage caused by bogus mails (Faked Spam/Virus). For peoples 
    that want to reduce CPU usage caused by bogus mails.
    For peoples that don't want to lose legitimate mails.
	


1.3 Requirements

    postfix ;-)    (script was tested with 2.1.5)
    perl 5.8 (5.6 might work, too)
    perl modules: Fcntl
                  Sys::Syslog
                  Net::DNS

    a caching DNS server in your network would not be bad, too!
    


2.0 How does it work

    Well, complex - but fast. To be continued (after stable release).
	A brief german description can be found at
	http://robtone.mine.nu/postfix/polw-deutsch-doc.txt


2.1 How to set it up

    copy policyd-weight to (preferably) /usr/libexec/postfix/policyd-weight
    set correct permissions (chmod a+rx /usr/libexec/postfix/policyd-weight)

    create a unix system account for user and group "polw"

    edit:
    [master.cf]:

    policy  unix  -       n       n       -       -       spawn 
    	user=polw argv=/usr/bin/perl /usr/libexec/postfix/policyd-weight


    [main.cf]:

    Remove reject_rbl_client checks.
    
    smtpd_recipient_restrictions =
    ...
    reject_unauth_destination
    check_policy_service unix:private/policy
    ...

    Important, keep your old SASL permits, they must come before 
    check_policy_service


2.2 How to read/understand the LOGs

    Depending on your version of grep:

    	grep "rate: " /var/log/maillog | grep -v "rate: (-|0)"
    		OR
    	grep "rate: " /var/log/maillog | grep -v "rate: \(-\|0\)"
    
    will show rejected mails.

    	grep "rate: \(-\|0\)" /var/log/maillog
    		OR
    	grep "rate: (-|0)" /var/log/maillog
    
    will show passed policyd-weight mails.

    To be continued.


3.0 Thanks

    to: Ralf Hildebrandt, it was him who set me on fire, also for his tests.
        Bob Tito, for testing and feeding me with results
        All Spammers that provided me with food and enlargement pills.
        To the mailing-list users which reported bugs and odd behavior.

