NAME

Mail::Decency::ContentFilter

SYNOPSIS

use Mail::Decency::ContentFilter;

my $content_filter = Mail::Decency::ContentFilter->new( {
    config => '/etc/decency/content-filter.yml'
} );

$content_filter->run;

DESCRIPTION

Postfix:Decency::ContentFilter implements multiple content filter

POSTFIX

You have to edit two files: master.cf and main.cf in /etc/postfix

master.cf

Add the following to the end of your master.cf file:

# the decency server itself
decency	unix  -       -       n       -       2        smtp
    -o smtp_send_xforward_command=yes
    -o disable_dns_lookups=yes
    -o max_use=20

# this is only required if you use virus or spam filters with bouncing
decency-bounce unix	-	n	n	-	2	pipe
    flags=FR user=decency argv=/etc/decency/bouncer

# re-inject mails from decency for delivery
127.0.0.1:10250      inet  n       -       -       -       -       smtpd
    -o content_filter= 
    -o receive_override_options=no_unknown_recipient_checks,no_header_body_checks,no_milters
    -o smtpd_helo_restrictions=
    -o smtpd_client_restrictions=
    -o smtpd_sender_restrictions=
    -o smtpd_recipient_restrictions=permit_mynetworks,reject
    -o mynetworks=127.0.0.0/8
    -o smtpd_authorized_xforward_hosts=127.0.0.0/8

# re-inject mails from decency for bouncing
# this is only required if you use virus or spam filters with bouncing
127.0.0.1:10260	inet	n	-	-	-	-	smtpd
    -o content_filter=decency-bounce
    -o receive_override_options=no_unknown_recipient_checks,no_header_body_checks,no_milters
    -o smtpd_helo_restrictions=
    -o smtpd_client_restrictions=
    -o smtpd_sender_restrictions=
    -o smtpd_recipient_restrictions=permit_mynetworks,reject
    -o mynetworks=127.0.0.0/8
    -o smtpd_authorized_xforward_hosts=127.0.0.0/8

main.cf

There are two possible ways you can include this content filter into postfix. The first is via content_filter, the second via check_*_access, eg check_client_access.

• content_filter

  The advantage: it is easy. The disadvantage: all mails (incoming, outgoing) will be filtered. In a one-mailserver-for-all configuration this might be ugly.

  # main.cf
  content_filter = decency:127.0.0.1:12345

• Via check_*_access

  And example using pcre on all mails would be:

  # main.cf
  smtpd_client_restrictions =
      check_client_access = pcre:/etc/postfix/decency-filter, reject

  Then in the /etc/postfix/decency-filter file:

  # /path/to/access
  /./ FILTER decency:127.0.0.1:12345

CONFIG

Provide either a hashref or a YAML file.

Example:

---

# enable log to syslog
enable_syslog: 1

# enable log to STDERR (for forground mode)
enable_warn: 1

# log output level .. 0 to 5
log_level: 20

# directory for saving mails temporarily while filtering
spool_dir: /tmp/deceny-filter-spool


# if the content filter does not use the same cache as the policy does
#   and you use foward_scoring, then you should set a keyword which
#   proves that the header originates from the policy server and is not
#   injected by a spammer!
policy_verify_key: /etc/decency/sign.pub

# this enables receival of scoring results from the policy server
accept_scoring: 1

# how to handle spam (if you use spam modules)
spam:
    
    # there are three:
    #   scoring = check through all scoring capable modules, account, decide
    #   strict = first module find anything wrong triggers handling
    #   ignore = dont do anything, just run the modules (for debugging)
    behavior: scoring
    
    # if behavior is scoring: amount of score to consider the mail as spam
    threshold: -150
    
    # if spam (scoring+score>threshold or strict), what to do
    #   tag = tag mail (X-Decency) as spam
    #   bounce = send back to sender (BACKSCATTER! NOT A GOOD IDEA)
    #   delete = silently remove (for the hardcore haters)
    handle: bounce
    
    # only for handle = tag, prefix for the subject of spam mails 
    #spam_subject_prefix:

# how to handle virus mails (if you use antivirus modules)
virus:
    # what to do with virus mails?
    #   bounce = send back (without virus!) to sender
    #   delete = remove mail permanently
    #   quarantine = move into quarantine directory (below)
    #   ignore = don't do anything (for debugging)
    handle: bounce
    
    # wheter send a notification to the recipient or not. 
    #   does not work with handle = ignore (of course)
    notify: 0


database:
    type: dbi
    args:
        - 'dbi:SQLite:dbname=/tmp/decency.db'

cache:
    class: File
    cache_root: /tmp/decency-cache

# all the content filters to use
#   the order they are provided here will be the order
#   they are applied
#   so you might want to put virus filters in the front, then
#   spam filters, then any possible manipulation filters
filters:

                                     

CLASS ATTRIBUTES

spool_dir

The directory where to save received mails before filtering

temp_dir

Holds temp files for modules

queue_dir

Holds queued mails (currently working on)

mime_output_dir

Directory for temporary mime output .. required by MIME::Parser

Defaults to spool_dir/mime

reinject_failure_dir

Directory for reinjection failures

Defaults to spool_dir/failure

quarantine_dir

Directory for quarantined mails (virus, spam)

Defaults to spool_dir/quarantine

spam_*

There is either spam scoring, strict or keep.

Keep account on positive or negative score per file. Each filter module may increment or decrement score on handling the file. The overall score determines in the end wheter to bounce or re-inject the mail.

virus_*

Virus handling

policy_verify_key

session_data

SessionItem (Mail::Decency::Core::SessionItem::ContentFilter) of the current handle file

METHODS

init

INit cache, database, logger, dirs and content filter

init_dirs

Inits the queue, checks spool dir for existing files -> read them

init_content_filters

Reads all content filters, creates instance and add to list of filters

start

Starts all POE servers without calling the POE::Kernel->run

run

Start and run the server via POE::Kernel->run

train

get_handlers

handle

Calls the handle method of all registered filters.

Will be called from the job queue

finish_spam

Got a spam mail -> handle it as spam. Either bounce, tag or delete

• delete

  With this handle, the mail will be removed. A notification might be send to the recipient.

• bounce

  The mail is bounced back to the sender.

finish_virus

Reinject mail into mailserver

finish_ok

Reinject mail into mailserver

reinject

Reinject mails to postfix queue, or archive in send-queue

send_notify

Encapses a mime mail with either virus or spam template.

session_init

Returns hashref of info's about a mail (file) .. containgin original "MAIL FROM" (from), "RCPT TO" (to), if anyone requires the pre-encoded mime, then also mime object

session_write_cache

Write mail info to caches

add_spam_score

Add score to global counter for current filter queue

virus_info

Call found a virus from module

_save_mail_to_dir

Save a mail to some dir. Called from quarantine or reinjection failures

AUTHOR

Ulrich Kautz <uk@fortrabbit.de>

COPYRIGHT

Copyright (c) 2010 the "AUTHOR" as listed above

LICENCSE

This library is free software and may be distributed under the same terms as perl itself.

cpanm Mail::Decency

perl -MCPAN -e shell
install Mail::Decency