'\" t .\" .\" .\" Title: courierperlfilter .\" Author: Sam Varshavchik .\" Generator: DocBook XSL Stylesheets vsnapshot .\" Date: 07/24/2017 .\" Manual: Double Precision, Inc. .\" Source: Courier Mail Server .\" Language: English .\" .TH "COURIERPERLFILTER" "8" "07/24/2017" "Courier Mail Server" "Double Precision, Inc." .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" courierperlfilter \- Sample Perl\-based mail filter .SH "SYNOPSIS" .HP \w'\fBfilterctl\fR\ 'u \fBfilterctl\fR [[start] | [stop]] [perlfilter] .SH "DESCRIPTION" .PP 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 \fBperlfilter\fR wrapper can create multiple \fBperlfilter\fR processes, so that multiple processes are used to filter incoming mail\&. .PP \fBperlfilter\fR requires Perl 5\&.10 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 \fBfilterctl start perlfilter\fR to activate filtering (if necessary, run \fBcourierfilter start\fR to start the mail filtering subsystem)\&. .SS "Setting up a Perl script" .PP Most of the ugly details of connecting the Perl script to Courier\*(Aqs 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\&. .PP 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 \fBfilterdata\fR() function to process the data file\&. The data file contains the actual message\&. The \fBfiltercontrol\fR() 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 \fBfilterdata\fR() that blocks messages with corrupted headers\&. The example script doesn\*(Aqt do anything interesting with \fBfiltercontrol\fR()\&. .PP \fBfilterdata\fR() and \fBfiltercontrol\fR() 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)\&. .SH "CREDITS" .PP A lot of the Perl glue code is based on examples from the perlembed manual page, and other sources\&. .SH "FILES" .PP \fBperlfilter\fR uses the following configuration files\&. Changes to the following files do not take effect until the filter has been stopped and restarted\&. .PP /etc/courier/filters/perlfilter\-mode .RS 4 If this file exists and contains the word "all", \fBperlfilter\fR will create its socket in /var/lib/courier/allfilters, otherwise the socket will be created in /var/lib/courier/filters, see \m[blue]\fB\fBcourierfilter\fR(8)\fR\m[]\&\s-2\u[1]\d\s+2 for more information\&. .RE .PP /etc/courier/filters/perlfilter\-numprocs .RS 4 This file contains a number that sets how many \fBperlfilter\fR processes are created\&. The default is 5 processes\&. There\*(Aqs always an extra \fBperlfilter\fR process that\*(Aqs used to clean up crashed child processes\&. .RE .PP /etc/courier/filters/perlfilter .RS 4 This file MUST exist and it must contain a single line of text with the filename of the Perl script to load\&. .RE .PP /usr/lib/courier/perlfilter\-example\&.pl .RS 4 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\&. .RE .PP /usr/lib/courier/perlfilter\-ratelimit\&.pl .RS 4 This is a complete Perl\-based filter than implements basic rate\-limiting features\&. .RE .PP 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\&. .SH "SEE ALSO" .PP \m[blue]\fB\fBcourierfilter\fR(8)\fR\m[]\&\s-2\u[1]\d\s+2\&. .SH "AUTHOR" .PP \fBSam Varshavchik\fR .RS 4 Author .RE .SH "NOTES" .IP " 1." 4 \fBcourierfilter\fR(8) .RS 4 \%http://www.courier-mta.org/courierfilter.html .RE