8.5 Using sa-exim
| ‚ < ‚ Day Day Up ‚ > ‚ |
8.5 Using sa-eximExim calls its local_scan( ) function once just before accepting a message (via SMTP or from a local process). By default, this function does nothing ‚ the implementation of the function in Exim's source code simply instructs Exim to accept the message. What makes local_scan( ) powerful is that you can replace Exim's version with your own code to perform custom message-checking. This function can be a good place to perform spam-checking. Even better, you don't have to write a new local_scan( ) yourself if you want to invoke SpamAssassin. Marc Merlin has written one for you: sa-exim. sa-exim invokes spamc in its local_scan( ) function and can thus take advantage of all of spamd 's configuration options. This section describes the installation and configuration of sa-exim. You can download it at http://sa-exim.sf.net. It requires Exim 4.11 or later. 8.5.1 Buiding sa-exim for Static IntegrationOnce you've unpacked the source code, you can choose one of two approaches to integrating sa-exim with Exim. This section focuses on static integration , which embeds sa-exim within Exim at compile time. The examples in this section assume you have unpacked Exim's source code in /usr/local/src/exim-4.30 and sa-exim's in /usr/local/src/sa-exim-3.1 .
To use the static integration approach, you edit sa-exim's sa-exim.c file, then replace Exim's src/local_scan.c file with sa-exim's sa-exim.c file, copy sa-exim's sa-exim.h file to the same location, and recompile (and reinstall) Exim. The local_scan( ) function in sa-exim.c replaces the default function. Two macro definitions in sa-exim.c must be edited. They appear in the code under the comment "Compile time config values" and provide the location of spamc (by default, /usr/bin/spamc ) and sa-exim's own configuration file (by default, /etc/exim4/sa-exim.conf , but you might change this location to /usr/exim/sa-exim.conf or /etc/sa-exim.conf as suits your system). $ cd /usr/local/src/sa-exim-3.1 ...Edit sa-exim.c in your favorite editor... $ make sa-exim.h echo "char *version=\"`cat version` (built `date`)\";" > sa-exim.h $ cp sa-exim.c ../exim-4.30/src/local_scan.c $ cp sa-exim.h ../exim-4.30/src $ cd ../exim-4.30 $ make $ su Password: XXXXXXXX # make install The static integration approach is easy but requires you to recompile Exim whenever you want to update sa-exim. 8.5.2 Building sa-exim for Dynamic IntegrationUsing the dynamic integration approach, you patch Exim to allow the local_scan( ) function to be dynamically loaded at runtime, and you compile sa-exim as a dynamically loadable executable. Many packaged versions of Exim are distributed with the dynamic loading patch already applied, but sa-exim includes two versions of the patches by David Woodhouse that you can apply to your Exim source code yourself. Use localscan_dlopen_up_to_4.14.patch to patch Exim versions 4.11 to 4.14; use localscan_dlopen_exim_4.20_or_better.patch to patch Exim 4.20 and later versions. Example 8-10 illustrates the patch process. Example 8-10. Patching Exim to support dynamic loading$ cd /usr/local/src/exim-4.30 $ patch -p1 < ../sa-exim-3.1/localscan_dlopen_exim_4.20_or_better.patch patching file src/EDITME Hunk #1 succeeded at 505 (offset 117 lines). patching file src/config.h.defaults Hunk #1 succeeded at 20 (offset 3 lines). patching file src/globals.c Hunk #1 succeeded at 108 (offset 5 lines). patching file src/globals.h Hunk #1 succeeded at 72 (offset 5 lines). patching file src/local_scan.c patching file src/readconf.c Hunk #1 succeeded at 224 (offset 42 lines). $ make $ su Password: XXXXXXXX # make install After installing the patched Exim, compile sa-exim as a dynamically loadable object file by editing its Makefile . Check that the definitions of CC , CFLAGS , and LDFLAGS are suitable for building a shared object file with your compiler. Set the following macros in the Makefile :
Run make to compile sa-exim; make should produce the shared object files sa-exim-3.1.so and accept.so . The former is the sa-exim replacement for the local_scan( ) function. The latter is a replacement for local_scan( ) that simply accepts all messages; you can use accept.so to test that dynamic loading works properly without the complexities of sa-exim. Copy these shared object files to an appropriate Exim directory (e.g., /usr/exim or /usr/exim/libexec ), and add the following lines to the beginning of Exim's configuration file: local_scan_path = /usr/exim/accept.so #local_scan_path = /usr/exim/sa-exim-3.1.so Restart Exim, and confirm that messages are being received. After you finish configuring sa-exim, edit Exim's configuration file again, comment out the accept.so line, uncomment the sa-exim.so line, and restart Exim again to activate sa-exim. 8.5.3 Configuring SpamAssassin for sa-eximsa-exim invokes SpamAssassin using spamc , so you must be running the spamd daemon to use sa-exim. sa-exim behaves as you'd expect with most of the settings you'd be likely to have in your sitewide configuration file (typically /etc/mail/spamassassin/local.cf ). One that requires particular care, however, is the report_safe setting. If you set report_safe to 0, SpamAssassin only adds spam-tagging headers and does not modify the body of messages. This setting works with sa-exim without any additional configuration and provides the fastest message-checking performance. If you prefer to have SpamAssassin modify the body of the message to add its report and convert the original message into an attachment, you can set report_safe to 1 (include original message as message/rfc822 attachment) or 2 (include original message as text/plain attachment). In this case, you have to set the SARewriteBody variable in sa-exim.conf (described in the next section). Because sa-exim must read the modified body back from SpamAssassin, message-checking will be slightly slower than with report_safe 0. In addition, if you perform message-archiving, the archives will contain the SpamAssassin-modified message. Finally, ensure that spamd is not being invoked with the --create-prefs option, as it should run as an unprivileged user and be unable to create user preference files anyway. You may wish to include the --nouser-config option as well. 8.5.4 Configuring sa-eximYou configure sa-exim by editing its sa-exim.conf configuration file. During the build of sa-exim, you should have specified a location for this file. Begin configuration by copying the sa-exim.conf file included with the sa-exim source code to this location. Edit the file to configure sa-exim. The sa-exim.conf file is copiously commented. As the first comment describes, sa-exim is picky about the formatting of options in this file. For example, the following are examples of valid options in sa-exim.conf : SApermreject: 12.0 SARewriteBody: 0 # The option below is commented out, and thus not set #SApermrejectsave: /var/spool/exim/SApermreject But none of this next set of options are valid: # No spaces are allowed before the colon! One and only one is required after! Sapermreject :12.0 # Only thresholds may be floating point numbers! SARewriteBody: 0.0 # This sets the option, with an empty value! Not the way to unset it! SApermrejectsave: Later definitions of the same option override earlier ones. The configuration file determines how sa-exim handles spam: sa-exim can accept messages (returning a 2xx SMTP code), accept and discard messages, temporarily fail messages (returning a 4xx SMTP code), reject messages (returning a 5xx SMTP code), or perform teergrubing during the SMTP connection. For each sa-exim action, you can control at what spam threshold the action is triggered, whether a message that triggered the action should be saved to an archive directory, and the location of the archive directory. sa-exim usually names files in the archive directory by concatenating the time (in seconds since 00:00:00 UTC on January 1, 1970) and the value of the Message-ID header of a given message.
The following sections examine the options in the sa-exim.conf configuration file. 8.5.4.1 Choosing messages on which to run SpamAssassinThe SAEximRunCond option specifies an Exim conditional expression that will be evaluated to determine whether SpamAssassin should be invoked on a message. To disable SpamAssassin, comment the option out or set its value to 0. To enable SpamAssassin on all messages, set the option's value to 1. The configuration file presents an example of how you can set this variable to check all messages except those originating from the local host or those with an X-SA-Do-Not-Run: Yes header: SAEximRunCond: ${if and {{def:sender_host_address} {!eq {$sender_host_address}{127.0. 0.1}} {!eq {$h_X-SA-Do-Not-Run:}{Yes}} } {1}{0}} 8.5.4.2 Choosing messages on which to take antispam actionsThe SAEximRejCond option specifies an Exim conditional expression that will be evaluated to determine whether sa-exim should take actions on messages that SpamAssassin considers spam. By disabling the option, you can have messages checked by SpamAssassin (and tagged, if appropriate) but unconditionally accepted. The configuration file provides an example in which actions are taken on all spam messages except those with an X-SA-Do-Not-Rej: Yes header: # X-SA-Do-Not-Rej should be set as a warn header if mail is sent to postmaster # and abuse (in the RCPT ACL), this way you're not bouncing spam abuse reports # sent to you SAEximRejCond: ${if !eq {$h_X-SA-Do-Not-Rej:}{Yes} {1}{0}} The X-SA-Do-Not-Run and X-SA-Do-Not-Rej headers can be added by the acl_smtp_rcpt ACL in Exim's own configuration file, using directives such as these: warn message = X-SA-Do-Not-Run: Yes hosts = +relay_from_hosts warn message = X-SA-Do-Not-Run: Yes authenticated = * warn message = X-SA-Do-Not-Rej: Yes local_parts = postmaster:abuse These ACL directives will add X-SA-Do-Not-Run headers to messages from authenticated senders or from hosts from which Exim should relay messages, and will add X-SA-Do-Not-Rej headers to messages to postmaster or abuse . The X-SA-Do-Not-Run header should be removed before messages are relayed to remote hosts; add a headers_remove directive in the definition of the remote_smtp transport: remote_smtp: driver = smtp headers_remove = "X-SA-Do-Not-Run" You may wish to use different header names or values to prevent spammers from guessing your header and adding it to their spam messages to bypass sa-exim. 8.5.4.3 Limiting how much of the message is fed to SpamAssassinSAmaxbody determines how many bytes of a message body sa-exim will feed to SpamAssassin for checking; it defaults to 256,000. If SATruncBodyCond evaluates to a false value, messages larger than SAmaxbody are not scanned at all. If SATruncBodyCond evaluates to a true value, such messages are truncated, and the first SAmaxbody bytes are scanned. This is generally not a good idea because proper MIME message formatting requires a closing MIME boundary string at the end of a message, and if SpamAssassin receives a partial body missing this string, it may complain that the message is misformatted. 8.5.4.4 Allowing SpamAssassin to rewrite message bodiesIf you set SpamAssassin's report_safe option to 1 or 2 (asking SpamAssassin to rewrite message bodies), you must set the SARewriteBody variable to 1. 8.5.4.5 Archiving messages when actions are takenArchiving message bodies preserves copies of messages in case they are needed later, and archived messages can be used as a quarantine system. The value of SAmaxarchivebody determines the amount of a message (in bytes) to save when archiving messages after taking action on them. It defaults to 20,971,520 (20MB), which is a reasonable value. Similarly, SAerrmaxarchivebody determines the number of bytes of a message to save when a message causes an error in sa-exim. It defaults to 1,073,741,824 (1GB). If SAPrependArchiveWithFrom is set to 1, sa-exim will add fake From lines to the beginning of archived messages so that the archive file will be in standard mbox format. This is usually desirable because it's easy to use most mail readers to examine an mbox file. 8.5.4.6 Passing SMTP senders and recipients to SpamAssassinBecause sa-exim is invoked at the end of the SMTP DATA step, it has access to the list of recipients provided in the SMTP RCPT commands from the sending MTA. If you set SAmaxrcptlength to a value higher than 0, sa-exim adds an X-SA-Exim-Rcpt-To header containing the list of recipients as long as the list doesn't exceed the smaller of SAmaxrcptlength bytes or 8 KB. sa-exim also has access to the SMTP MAIL FROM command and adds the SMTP sender to the message in the X-SA-Exim-Mail-From header The recipient list can be useful to SpamAssassin, as messages with a large number of recipients might be more likely to indicate spam, and the true list of recipients may not appear in the message To and Cc headers. Similarly, knowing the SMTP sender might help identify a known spammer or a spammer using an invalid sender address. By setting the SAaddSAEheaderBeforeSA option to 1, you direct sa-exim to add these headers before invoking SpamAssassin on a message, which is the default. Set SAaddSAEheaderBeforeSA to 0 if you prefer SpamAssassin to see messages with no sa-exim headers added.
8.5.4.7 Setting a timeout on spamcsa-exim must wait for spamc to check messages but should not wait forever. By setting SAtimeout to a value in seconds, you ensure that if spamc should fail to check a message in a reasonable time, the message will be accepted. If you set SAtimeout to 0 (or to more than 300 seconds), Exim itself will interrupt a spamc run after five minutes, but it will cause the SMTP connection to return a temporary failure for the message, instead of accepting it. I recommend that you set SAtimeout and use a value between 60 and 240 seconds. If a message is accepted due to a spamc timeout, and you set SAtimeoutsave to the absolute path of a directory, the message will be saved in that directory so you can see the impact of your SAtimeout settings. The directory must be writable by the Exim user; if it does not exist, sa-exim will attempt to create it. You can limit which of these messages are saved by defining SAtimeoutSavCond to an Exim conditional expression. When spamc times out checking a message and the conditional expression returns a true value, the message will be saved. The default SAtimeoutSavCond is 1, which saves all messages when spamc times out. 8.5.4.8 Handling messages that cause sa-exim errorsBecause sa-exim is a robust framework, it considers the possibility that a message might cause an error in sa-exim itself and provides the ability to handle such messages. If a message causes an error, and you set SAerrorsave to the absolute path of a directory, the message will be saved in that directory. The directory must be writable by the Exim user; if it does not exist, sa-exim will attempt to create it. You can limit which error- causing messages are saved by defining SAerrorSavCond to an Exim conditional expression. If an error occurs and the conditional expression returns a true value, the message will be saved. The default SAerrorSavCond is 1, which saves all messages that cause sa-exim errors. By default, sa-exim will accept messages that cause errors, which prevents mail loss. An alternative is to have sa-exim instruct Exim to temporarily fail such messages, which will cause the sending MTA to queue them and retry delivery later. To temporarily fail messages that cause errors, set SAtemprejectonerror to 1. Set the SAtemprejectonerror variable to change the message that will be returned to the sending MTA when a message is temporarily failed by setting the SAmsgerror variable. 8.5.4.9 TeergrubingIf you want sa-exim to perform teergrubing of a connection when spam is detected , set the SAteergrube variable to the SpamAssassin spam score at or above which teergrubing should take place. If you don't define this variable, sa-exim will not teergrube. See the sidebar Teergrubing, earlier in this chapter for an explanation of that technique. Set the SAteergrubcond variable to an Exim conditional expression to determine whether teergrubing should be performed when the spam score exceeds the SAteergrube threshold; teergrubing will be performed only when the expression evaluates to a true value. Use this variable to prevent teergrubing from affecting you or your secondary mail exchangers. The default sa-exim.conf file includes the following example, which prevents teergrubing of connections from 127.0.0.1 and 127.0.0.2: SAteergrubecond: ${if and { {!eq {$sender_host_address}{127.0.0.1}} {!eq {$sender_ host_address}{127.0.0.2}} } {1}{0}} You can configure the teergrube delay ‚ the total amount of time, in seconds, that you want to try to tie up the sending MTA ‚ by setting the SAteergrubetime variable. The default is 900 (15 minutes). Every ten seconds during the teergrubing period, sa-exim will transmit SMTP code 451 with the reason given in SAmsgteergrubewait (which defaults to "wait for more output"). At the end of the teergrubing period, sa-exim will temporarily fail the message with the reason given in SAmsgteergruberej (which defaults to "Please try again later"). sa-exim temporarily fails the messages in the hopes that the sending MTA will later attempt to resend the message and spend more time in the tar pit. If a message qualifies a connection for teergrubing, and you set SAteergrubesave to the absolute path of a directory, the message will be saved in that directory. The directory must be writable by the Exim user; if it does not exist, sa-exim will attempt to create it. You can limit which of these messages are saved by defining SAteergrubeSavCond to an Exim conditional expression. If the conditional expression returns a true value, the message will be saved. The default SAteergrubeSavCond is 1, which saves all messages that trigger teergrubing. Because sa-exim temporarily fails teergrubed mail after the teergrubing period, the sending MTA is likely to resend the same message. If you are saving messages that trigger teergrubing, it could lead to repeatedly saving multiple copies of the same message. To prevent this, set SAteergrubeoverwrite to 1 (which is the default), and sa-exim will use only the message ID as the filename when saving teergrubed messages. Because resends should have the same message ID, this will result in a single copy of the message being kept, as older copies are overwritten by newer copies assigned the same filename. 8.5.4.10 Accepting and discarding spamIf you want sa-exim to accept and discard spam, set the SAdevnull variable to the SpamAssassin spam score at or above which messages should be accepted and discarded. If you don't define this variable, sa-exim will not take those actions. If a message is to be discarded, and you set SAdevnullsave to the absolute path of a directory, the message will be saved in that directory. The directory must be writable by the Exim user; if it does not exist, sa-exim will attempt to create it. You can limit which of these messages are saved by defining SAdevnullSavCond to an Exim conditional expression. If the conditional expression returns a true value, the message will be saved. The default SAdevnullSavCond is 1, which saves all messages that are discarded. 8.5.4.11 Rejecting spamIf you want sa-exim to reject spam during the SMTP connection, set the SApermreject variable to the SpamAssassin spam score at or above which messages should be rejected. If you don't define this variable, sa-exim will not take this action. You can customize the rejection explanation that is sent along with the SMTP rejection code by setting SAmsgpermreject . If a message is to be rejected, and you set SApermrejectsave to the absolute path of a directory, the message will be saved in that directory. The directory must be writable by the Exim user; if it does not exist, sa-exim will attempt to create it. You can limit which of these messages are saved by defining SApermrejectSavCond to an Exim conditional expression. If the conditional expression returns a true value, the message will be saved. The default SApermrejectSavCond is 1, which saves all messages that are rejected. 8.5.4.12 Temporarily failing spamIf you want sa-exim to temporarily fail spam during the SMTP connection, set the SAtempreject variable to the SpamAssassin spam score at or above which messages should be temporarily failed. If you don't define this variable, sa-exim will not take this action. You can customize the rejection explanation that is sent along with the SMTP rejection code by setting SAmsgtempreject . If a message is to be temporarily failed, and you set SAtemprejectsave to the absolute path of a directory, the message will be saved in that directory. The directory must be writable by the Exim user; if it does not exist, sa-exim will attempt to create it. You can limit which of these messages are saved by defining SAtempmrejectSavCond to an Exim conditional expression. If the conditional expression returns a true value, the message will be saved. The default SAtemprejectSavCond is 1, which saves all messages that are temporarily failed. When sa-exim temporarily fails a message, the sending MTA is likely to resend the same message. If you are saving messages that trigger temporary rejections, this could lead to repeatedly saving multiple copies of the same message. To prevent this, set SAtemprejectoverwrite to 1 (which is the default), and sa-exim will use only the message ID as the filename when saving temporarily failed messages. Because resends should have the same message ID, this will result in single copies of messages being kept, as older copies are overwritten by newer copies assigned the same filename. There are few good reasons to temporarily fail spam. If you do not want to receive spam at all, permanently reject or accept and discard it instead. If you want to tie up spammer MTAs, teergrube instead. sa-exim includes temporary failing for completeness, but I do not recommend its use. 8.5.4.13 Archiving accepted spamWhen sa-exim receives a message that SpamAssassin tags as spam but that does not meet any of the sa-exim action thresholds, sa-exim will accept the (tagged) message and allow it to be delivered to the recipient. If a message is to be accepted, and you set SAspamacceptsave to the absolute path of a directory, the message will be saved in that directory. The directory must be writable by the Exim user; if it does not exist, sa-exim will attempt to create it. You can limit which of these messages are archived by defining SAspamacceptSavCond to an Exim conditional expression. If the conditional expression returns a true value, a message will be archived. The default SAspamacceptSavCond is 0, which does not archive any accepted spam messages. Although this feature is not useful for end users, mail administrators can use it to help decide whether to lower one of the other action thresholds by examining the saved messages. If there are no false positives, you might lower the action thresholds. 8.5.4.14 Archiving non-spam messagesWhen sa-exim receives a message that SpamAssassin does not consider spam, sa-exim will (of course) accept the message and allow it to be delivered to the recipient. If a non-spam message is received, and you set SAnotspamsave to the absolute path of a directory, the message will be saved in that directory. The directory must be writable by the Exim user; if it does not exist, sa-exim will attempt to create it. You can limit which of these messages are saved by defining SAnotspamSavCond to an Exim conditional expression. If the conditional expression returns a true value, the message will be saved. The default SAnotspamSavCond is 0, which does not save any accepted non-spam messages. A mail administrator might use this feature to analyze a group of non-spam messages to determine whether SpamAssassin is making too many false negative judgments , but on a busy mail site, saving extra copies of all legitimate incoming mail is probably not a good idea. sa-exim includes this feature primarily for completeness. 8.5.4.15 Debugging sa-eximSet the SAEximDebug variable to a number between 1 and 9 to enable extra logging; higher numbers produce more debugging output. The distributed sa-exim.conf file sets this variable to 1, which will log a notice whenever sa-exim saves a new message to one of its archive directories, invokes spamc , rewrites message bodies, or evaluates an Exim conditional expression. Increasing SAEximDebug is a good idea, particularly when testing new conditional expressions. Example 8-11 shows a complete sa-exim.conf file (without comments). In this example, sa-exim is configured to reject (but save) messages with spam scores higher than 15. Example 8-11. A complete sa-exim.conf file # Run SpamAssassin unless the message was submitted locally or the # X-SA-Do-Not-Run header is set to 'secret'. We configure Exim elsewhere # to set this header for messages from authenticated senders or hosts # we relay for SAEximRunCond: ${if and {{def:sender_host_address} {!eq {$sender_host_address}{127.0.0. 1}} {!eq {$h_X-SA-Do-Not-Run:}{secret}} } {1}{0}} # Don't take action on messages if X-SpamAssassin-Do-Not-Rej header is set to # 'secret'. We configure Exim to set this header for messages to the postmaster. SAEximRejCond: ${if !eq {$h_X-SA-Do-Not-Rej:}{Yes} {1}{0}} # Feed up to 300Kb to SpamAssassin, and if the message is longer, don't # bother spam checkign SAmaxbody: 307200 SATruncBodyCond: 0 # We don't let SpamAssassin rewrite message bodies, so we don't set this SARewriteBody: 0 # I prefer to avoid the X-SA-Exim-Rcpt-To header, for privacy reasons. SAmaxrcptlistlength: 0 # Allow spamc 2 minutes for each message. If it times out, don't bother # saving messages, just accept them. SAtimeout: 120 SAtimeoutsave: SAtimeoutSavCond: 0 # Do save messages that cause an error in sa-exim, but accept them SAerrorsave: /var/spool/exim/SAerrorsave SAerrorSavCond: 1 SAtemprejectonerror: 0 # Reject messages with SpamAssassin scores of 15 or higher, but save a # copy of them. SApermreject: 15.0 SApermrejectSavCond: 1 SApermrejectsave: /var/spool/exim/SApermreject 8.5.5 Using Per-User PreferencesLike exiscan, sa-exim checks messages for spam just once ‚ at message receipt after the SMTP DATA command. And like exiscan, it's difficult to use SpamAssassin's per-user preference files with sa-exim. Messages may have multiple recipients, some of whom are not local, and sa-exim will not be able to determine whose preferences should be used. You can use per-user preferences with sa-exim in the same ways as you can with exiscan, and with the same performance costs:
|
| ‚ < ‚ Day Day Up ‚ > ‚ |
