.\" ** You probably do not want to edit this file directly ** .\" It was generated using the DocBook XSL Stylesheets (version 1.69.1). .\" Instead of manually editing it, you probably should edit the DocBook XML .\" source for it and then use the DocBook XSL Stylesheets to regenerate it. .TH "MILTER\-REGEX" "1M" "September 24, 2003" "milter\-regex 1.5" "" .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .SH "NAME" milter\-regex \- sendmail milter plugin for regular expression filtering .SH "SYNOPSIS" .HP 13 \fBmilter\-regex\fR [\-d] [\-c\ \fIconfig\fR] [\-n] [\-p\ \fIpipe\fR] [\-u\ \fIuser\fR] .SH "DESCRIPTION" .PP The \fBmilter\-regex\fR plugin can be used with the milter API of \fBsendmail\fR(1M) to filter mails using regular expressions matching SMTP envelope parameters and mail headers and body. .SH "OPTIONS" .TP \-d Enable verbose debug output, which will be logged via \fBsyslog\fR(3C) at the debug level for the mail facility. In case you are logging to a file, make sure to have a lot of space at the partition in question! .TP \-c \fIconfig\fR Use the specified configuration file instead of the default, /etc/mail/milter\-regex.conf. .TP \-n Usually \fBmilter\-regex\fR adds a heading to messages that are scanned. The header is of the form "X\-Milter: \fIversion\fR", this option instructs regex\-milter to refrain from adding this heading. .TP \-p \fIpipe\fR Use the specified pipe to interface \fBsendmail\fR(1M). Default is local:/var/milter/milter\-regex.sock. .TP \-u \fIuser\fR Run as the specified user instead of the default, smmsp. When \fBmilter\-regex\fR is started as root, it calls \fBsetuid\fR(2) to drop privileges. The non\-privileged user should have read access to the configuration file and read\-write access to the pipe. .SH "SENDMAIL CONFIGURATION" .PP \fBsendmail\fR(1M) needs to have milter support. To check, whether your sendmail has milter support, you may run: .sp .nf /usr/lib/sendmail \-d0.1 \-bp | grep MILTER .fi .PP If \fBMILTER\fR appears in the output, sendmail supports Mail Filter. .PP The milter aka plugin needs to be registered in the \fBsendmail\fR(1M) configuration, by adding the following lines to your sendmail m4 configuration file .IP .sp .nf INPUT_MAIL_FILTER(`milter\-regex', `S=local:/var/milter/milter\-regex.sock, T=S:30s;R:2m') .fi .PP and rebuilding /etc/mail/sendmail.cf (e.g. cd /etc/mail; ./mknewcf \-c server.mc) and restarting \fBsendmail\fR(1M). .SH "PLUGIN CONFIGURATION" .PP The configuration file consists of rules that, when matched, cause \fBsendmail\fR(1M) to reject mails. Emtpy lines and lines starting with # are ignored, as well as leading whitespace (blanks, tabs). Trailing backslashes can be used to wrap long rules into multiple lines. Each rule starts with one of the following commands: .TP \fB reject\fR "message" Subsequent rules cause the mail to be rejected with a permanent error consisting of the specified text part. The SMTP reply consists of the three\-digit code \fB550\fR (RFC 2821 "command rejected for policy reasons"), the extended reply code \fB5.7.1\fR (RFC 1893 "Permanent Failure", "Security or Policy Status", "Delivery not authorized, message refused") and the text part (which defaults to "Command rejected", if not specified). This is a permanent failure, which causes the sender to remove the message from its queue without trying to retransmit, commonly generating a bounce message to the sender. .TP \fB tempfail\fR "message" Subsequent matching rules cause the mail to be rejected with a temporary error consisting of the specified text part. The SMTP reply consists of the three\-digit code \fB451\fR (RFC 2821 "Requested action aborted: local error in processing"), the extended reply code \fB4.7.1\fR (RFC 1893 "Persistent Transient Failure", "Security or Policy Status", "Delivery not authorized, message refused") and the text part (which defaults to "Please try again later", if not specified). This is a temporary failure, which causes the sender to keep the message in its queue and try to retransmit it, commonly for several days. .TP \fB discard \fR Subsequent matching rules cause the mail to be accepted but then discarded silently. Note that \fBconnect\fR and \fBhelo\fR rules should not use \fBdiscard\fR. .TP \fB accept \fR Subsequent matching rules cause the mail to be accepted without further rule evaluation. Can be used for whitelist criteria. .PP A command is followed by one or more expressions, each causing the previous command to be executed when matched. The following expressions can be used: .TP \fBconnect\fR \fIhostname\fR \fIaddress\fR Reject the connection if both the sender's hostname and address match the specified regular expressions. The numerical address is either dotted\-quad (IPv4) or coloned\-hex (IPv6). The hostname is the result of a DNS reverse resolution of the numerical address (which \fBsendmail\fR(1M) performs independantly of the milter plugin). When resolution fails, the hostname contains the numerical address in square brackets. .TP \fBhelo\fR \fIname\fR Reject the connection if the sender supplied \fBHELO\fR name matches the specified regular expression. Commonly, the sender supplies his fully\-qualified hostname as \fBHELO\fR name. .TP \fBenvfrom\fR \fIaddress\fR Reject the mail if the sender supplied envelope \fBMAIL FROM\fR address matches the specified regular expression. Addresses commonly have the form . .TP \fBenvrcpt\fR \fIaddress\fR Reject the mail if the sender supplied envelope \fBRCPT TO\fR address matches the specified regular expression. .TP \fBheader\fR \fIname\fR \fIvalue\fR Reject the mail if a header matches the specified name and value. For instance, the header "Subject: Test" matches name Subject and value Test. .TP \fBbody\fR \fIline\fR Reject the mail if a body line matches the specified regular expression. .SH "REGULAR EXPRESSIONS" .PP The regular expressions used in the configuration rules are enclosed in arbitrary delimiters, no further escaping is needed. .PP The first character of an argument is taken as the delimiter, and all subsequent characters up to the next occurance of the same delimiter are taken literally as the regular expression. Since the delimiter itself cannot be part of the regular expression (no escaping is supported), a delimiter must be chosen that doesn't occur in the regular expression itself. Each argument can use a different delimiter, all characters except spaces and tabs are valid. .PP Two immediately adjacent delimiters form an empty regular expression, which always matches and requires no \fBregexec\fR(3C) call. This can be used in rules requiring multiple arguments, to match only some arguments. .PP See \fBregex\fR(5) for a detailed description of basic and extended regular expressions. .PP Optionally, the following flags can be used after the closing delimiter: .TP \fBe\fR Extended regular expression. This sets \fBREG_EXTENDED\fR for \fBregcomp\fR(3C). .TP \fBi\fR Ignore upper/lower case. This sets \fBREG_ICASE\fR. .TP \fBn\fR Not matching. Reverses the matching result, i.e. the mail is rejected if the regular expression does not match. .SH "BOOLEAN EXPRESSIONS" .PP A rule can consist of either a simple term or more complex expressions. A term has the form .sp .nf header /From/ /domain/i .fi .PP and expressions can be built combining terms with operators \fBand\fR, \fBor\fR, \fBnot\fR and \fB( )\fR, as in .sp .nf header /From/ /domain/i and body /money/ \\ ( not header /From/ /domain/ ) and ( body /sex/ or body /fast/ ) .fi .PP Operator precedence should not be relied on, instead parentheses should be used to resolve any ambiguities (they usually produce syntax errors from the parser). .SH "MACROS" .PP Macros allow to store terms or expressions as a \fIname\fR, and \fI$name\fR can be used as term within other rules, expressions or macro definitions. Example: .sp .nf friends = header /^Received$/ /^from [^ ]*(ork.net|home.com)/e attachments = header ,^Content\-Type$, ,multipart/mixed, and \\ body ,^Content\-Type: application/, executables = $attachments and body ,name=".*.(pif|exe|scr)"$,e reject "executable attachment from non\-friends" $executables and not $friends .fi .PP Macro names must begin with a letter and may contain alphanumeric characters and punctuation characters. Reserved keywords (like \fBreject\fR or \fBheader\fR) cannot be used as macro names. Macros must be defined before use, the definition must precede the use in the configuration file, read from top to bottom. .SH "EVALUATION" .PP Rules are evaluated in the order specified in the configuration file, from top to bottom. When a rule matches, the correpsonding action is taken, that is the last action specified before the matching rule. .PP The plugin evaluates the rules every time a line of mail (or envelope) is received. As soon as a rule matches, the action is taken immediately, possibly before the entire mail is received, even if further lines might possibly make other rules match, too. This means the first rule matching chronologically has precendence. .PP If evaluation for a line of mail makes two (or more) rules match, the rule that comes first in the configuration file has precendence. .PP Boolean expressions are short\-circuit evaluated, that means "a or b" becomes true as soon as one of the terms is true and "a and b" becomes false as soon as one of the terms is false, even if the other term is not known, possibly because the relevant mail line has not been received yet. .SH "EXAMPLES" .sp .nf # /etc/mail/milter\-regex.conf example tempfail "Sender IP address not resolving" connect /\\[.*\\]/ // reject "Malformed HELO (not a domain, no dot)" helo /\\./n reject "Malformed RCPT TO (not an email address, not <.*@.*>)" envrcpt /<(.*@.*|Postmaster)>/ein reject "HTML mail not accepted" # use comma as delimiter here, as / occurs within RE header /^Content\-type$/i ,^text/html,i body ,^Content\-type: text/html,i # Swen worm discard header /^(TO|FROM|SUBJECT)$/e // header /^Content\-type$/i /boundary="Boundary_(ID_/i header /^Content\-type$/i /boundary="[a\-z]*"/ body ,^Content\-type: audio/x\-wav; name="[a\-z]*\\.[a\-z]*",i # Some nasty spammer reject "Business Corp spam, get lost" body /^Business Corp. for W.& L. AG/i and \\ ( body /043.*317.*0285/ or body /0041.43.317.02.85/ ) .fi .SH "LOGGING" .PP milter\-regex sends log messages to \fBsyslogd\fR(1M) using facility mail and, with increasing verbosity, level err, notice, info and debug. The following \fBsyslog.conf\fR(4) section can be used to log messages to a dedicated file: .sp .nf mail.err;mail.notice /var/log/milter\-regex.log mail.debug /var/aLotOfSpaceAvailable/mail\-debug.log .fi .SH "GRAMMAR" .PP Syntax for \fBmilter\-regex\fR in BNF: .sp .nf file = ( rule | macro ) file rule = action expr\-list action = "reject" msg | "tempfail" msg | "discard" | "accept" msg = ( '"' | "'" ) string ( '"' | "'" ) expr\-list = expr [ expr\-list ] expr = term | term "and" expr | term "or" expr | "not" term term = '(' expr ')' | "connect" arg arg | "helo" arg | "envfrom" arg | "envrcpt" arg | "header" arg arg | "body" arg | '$' name arg = del regex del flags del = '/' | ',' | '\-' | ... flags = [ 'e' ] [ 'i' ] [ 'n' ] macro = name '=' expr .fi .SH "FILES" .TP \fI/etc/mail/milter\-regex.conf\fR default configuration file .SH "SEE ALSO" .PP \fBregcomp\fR(3C), \fBsyslog.conf\fR(4), \fBregex\fR(5), \fBsendmail\fR(1M), \fBsyslogd\fR(1M) .PP The Internet Society (2001), [1]\&\fIRFC 2821 \- Simple Mail Transfer Protocol\fR, AT&T Laboratories, April 2001 .PP G. Vaudreuil, [2]\&\fIRFC 1893 \- Enhanced Mail System Status Codes\fR, Octel Network Services, January 1996 .SH "HISTORY" .PP The first version of milter\-regex was written in 2003. Boolean expression evaluation was added in 2004. .SH "AUTHORS" .TP 3 \(bu Daniel Hartmeier .SH "REFERENCES" .TP 3 1.\ RFC 2821 \- Simple Mail Transfer Protocol \%http://www.faqs.org/rfcs/rfc2821.html .TP 3 2.\ RFC 1893 \- Enhanced Mail System Status Codes \%http://www.faqs.org/rfcs/rfc1893.html