Provided by: courier-mta_0.47-13ubuntu5_i386 bug

NAME

       courierperlfilter - Sample Perl-based mail filter

SYNOPSIS

       filterctl [ start | stop ] [ perlfilter ]

DESCRIPTION

       This  is  an  example  global  mail  filter  that uses an embedded Perl
       script.  "Embedded" means that the Perl interpreter is loaded once, and
       the  same  Perl  code is repeatedly called to accept or reject incoming
       messages, one by one.  Perl  filtering  is  relatively  time  consuming
       (compared  to  filtering  in  C  or  C++), and excessive delays in mail
       filters result  in  incoming  mail  being  deferred  (rejected  with  a
       temporary  error  code).   Therefore  the perlfilter wrapper can create
       multiple perlfilter processes, so that multiple processes are  used  to
       filter incoming mail.

       perlfilter requires Perl 5.004 or higher. The best way to create a Perl
       filter is to start with the sample filter, /usr/lib/courier/perlfilter-
       example.pl.  This  filter  reject  messages that contain an excessively
       long Date:  header  (designed  to  crash  certain  poorly-written  mail
       clients).  Use  it  as  a  basis  for writing your own filter.  You can
       install your filter in any convenient  location,  then  initialize  the
       /etc/courier/filters/perlfilter configuration file, as described below.
       Run filterctl start perlfilter to activate filtering (if necessary, run
       courierfilter start to start the mail filtering subsystem).

   SETTING UP A PERL SCRIPT
       Most  of  the  ugly  details of connecting the Perl script to Courier’s
       mail filtering engine is  taken  care  of  by  the  sample  perlfilter-
       example.pl script. One big no-no: the script MAY NOT change the current
       directory. Anything else  goes,  for  the  most  part.   Loading  other
       modules and classes, pretty much anything else you can do with Perl, is
       allowed.

       The Perl script, just like any other mail filtering module, receives  a
       pointer  to  a  data  file  and  one or more control files, each time a
       message is submitted to Courier for delivery. The sample  script  calls
       the  filterdata()  function  to  process  the  data file. The data file
       contains the actual message. The filtercontrol() function is called  to
       process  each  control  file.   The control file contains recipient and
       message metadata.  There may be more than one  control  file  for  each
       message.  The example script includes an implementation of filterdata()
       that blocks messages with corrupted headers. The example script doesn’t
       do anything interesting with filtercontrol().

       filterdata()  and  filtercontrol()  must  return  an empty string if no
       serious objections are raised for this message. Any other return string
       is  interpreted  as an SMTP-style error code that is used to reject the
       message.  Care must be taken that  any  error  messages  are  formatted
       strictly  according  to  the format of SMTP error messages (even though
       the message may not actually come in via SMTP).

CREDITS

       A lot of the Perl glue code is based on  examples  from  the  perlembed
       manual page, and other sources.

FILES

       perlfilter  uses  the  following  configuration  files.  Changes to the
       following files do not take effect until the filter  has  been  stopped
       and restarted.

       /etc/courier/filters/perlfilter-mode
              If this file exists and contains the word "all", perlfilter will
              create its socket in /var/lib/courier/allfilters, otherwise  the
              socket   will   be   created  in  /var/lib/courier/filters,  see
              courierfilter(8) for more information.

       /etc/courier/filters/perlfilter-numprocs
              This file contains  a  number  that  sets  how  many  perlfilter
              processes  are  created.  The  default  is  5 processes. There’s
              always an extra perlfilter  process  that’s  used  to  clean  up
              crashed child processes.

       /etc/courier/filters/perlfilter
              This  file  MUST exist and it must contain a single line of text
              with the filename of the Perl script to load.

       /usr/lib/courier/perlfilter-example.pl
              This   is   a   sample   Perl   script   of   the   kind    that
              /etc/courier/filters/perlfilter points to.  Use it as an example
              of writing your own Perl filters.

       Please exercise good judgment  in  writing  Perl-based  filters.   They
       should  be  reasonably  fast,  and do not allocate megabytes of memory.
       They should not be very promiscuous in creating global Perl  variables,
       and  should  clean  up after themselves.  The current Perl wrapper does
       not destroy the Perl symbol table after each call to the filter script.
       However, do not take that for granted. This may change in the future.

SEE ALSO

       courierfilter(8).