Scope engine procedure reference. ------------------------------------------------------------------------------ This document is a quick reference of how to use the procedures contained in the procroot directory. The "usage" examples all assumes the proper use of [TAB] and [NEWLINE] separators. These are left out for the sake of readability. Examples also assume the Scope engine runs on the same machine listening on 127.0.0.1:7887, if yor run Scope on any other machine or interface you must supply the client with -s and -p options accordingly like so; "/path/to/scope_client" "/proc" "-file" "@@FILE" "-s" "1.2.3.4" "-p" "3333" ...or edit the scope.cpp source and modify the default host:port to what whatever your setup is, and roll your own version of the client, probably more handy in the long run. The Scope client requires any supplied XMail macro to have a key associated with it in order to be able to re-format the arguments into URI form for delivery to the Scope engine. So always, always prepend the macro-name along with a macro-value like so; "-file" "@@FILE", "-msgid" "@@MSGID" and so on... [Scope::autoreply] Autoreply features on a global or per-user level. ------------------------------------------------------------------------------ - Mode (in preferred order) ----------- mailproc, custdomains, cmdalias - Usage ------------------------------- "external" "-1" "0" "scope" "/autoreply" "-from" "@@FROM" "-rrcpt" "@@RRCPT" - Remarks ----------------------------- The -1 and 0 arguments reflects lo-priority and that XMail don't need to wait for this command to complete. Use macro @@RRCPT if available, fall back on @@RCPT as a second option. The autoreply procedure enables a user to automatically have a message sent in reply to incoming messages. The reply message can be defined per user or/and be a global template. On a per user basis, the procedure will first lookup the current user's 'user.tab' for an entry 'Scope-AutoReply-Template' pointing to a fullblown RFC822 message template and post that via LMAIL to the sender @@FROM. If the current @@RRCPT, doesn't have such a template defined/or a 'user.tab' couldn't be found (typically when using @@RCPT, since it might resolve to an alias), an optional default autoreply template message can be defined in the procedure conf to be used instead. (see lib/autoreply/autoreply.default) If you don't want the default template to step in, just leave that configuration entry to 0. Depending on conf settings you can enable global, per domain or per user replies. With the optional user.tab variable 'Scope-AutoReply-Skip' you can define a list of sender addresses which should not generate get a reply. The reply-templates acknowledges a few macro definitions such as %RCPT% %FROM%, %DATE% and everything in the user.tab file uppercased like %REALNAME%, %HOMEPAGE% etc. This way the messages can be personalized to some degree. [Scope::spamassasin] Wrapper procedure for Mail::SpamAssassin 2.42+ ------------------------------------------------------------------------------ - Mode (in preferred order) ----------- filter - Usage ------------------------------- "scope" "/spamassassin" "-file" "@@FILE" ["-rrcpt" "@@RRCPT"] "scope" "/SA" "-file" "@@FILE" - Remarks ----------------------------- Returns code 97 (Reject) upon Spam positive. Optionally you can enable archiving of all messages tagged as spam. (See conf.) An additional '-rrcpt' (XMail 1.11+) enables you apply per-user threshold feature with more reliability (in favor of '-rcpt'). The per-user threshold value is taken from 'Scope-SpamAssassin-Threshold' variable in the user.tab of the current recipient and as the @@RCPT might reflect an alias, the tab lookup will fail and Scope::spamassasin falls back on the default threshold value. The 'default-threshold' setting if present, overrides SA's 'required_hits' equivalent. Running Scope engine in double debug mode (-d -d) causes SA to spit out detailed scanning reports. And btw, You additionally need the Mail::SpamAssassin 2.42+ bundle available at either CPAN or the ActiveState's PPM repository. The Scope::spamassasin procedure wraps and intergrates the famous Mail::SpamAssassin spam-scanner with XMail and offers a huge performance improvement compared to using SA as the standalone application. Scope supersedes the need for SA's SPAMD/SPAMC applications, meaning the Scope::spamassasin implementation is fully cross-platform compatible. There are a number of configuration options available to customize the SA behavior, the default SA configuration and the bundled file (lib/spamassassin/user_prefs) are optimized for the Scope environment and shouldn't be altered too much unless you are sure what you are doing. As an extra, any changes to the user_prefs file are picked up in real-time without needing to restart Scope for the changes to take effect. Due to the resource intensitive job of scanning large messages, the maximum messages subjected to SA is limited to 256kb by default. Larger messages will pass through as-is, set this value higher if you like but I recommend a value around 200kb, since spam messages tend to be rather small. As of this writing, the latest SA version around is 2.50-cvs, and though this wrapper works very well with it, I still cannot recommend you use SA together with Scope on a high volume XMail system. The problem is that SA leaks memory, and it leaks badly!!! Running SA standalone as a script isn't a problem, but inside a persistent environment such as Scope and especially since its a PERL environment with its rather odd concept of garbage collection, memory leaks are fatally serious as it sooner or later will exhaust your RAM, the process will go through the roof and eventually you have got yourself a fine, self-inflicted denial of service. However, I have run this procedure on a productional system without hassle for several weeks by now and by setting the Scope engine to automatically re-start itself every 24h or so (see option 'regenerate'), you should be ok. Just remember to drop an eye on the Scope memory usage every now and then. [Scope::sizecheck] Accept/reject messages based on size. ------------------------------------------------------------------------------ - Mode (in preferred order) ----------- filter - Usage ------------------------------- "scope" "/sizecheck" "-file" "@@FILE" - Remarks ----------------------------- The default behavior is to return code 97 (Reject) if the message exceeds the defined max-size. Max-size and exceeding return code are configurables. This is a simplistic procedure rejecting or accepting messages to pass through depending on size, will work on outbound messages aswell as inbounds. You probably want to use XMail's builtin MaxMessageSize features infavor of this, but there might be situations this procedure comes in handy, such as for setting a size-limit on outbound messages, that is messages sent from a local user to the outside world. [Scope::signature] Apply per-user or global signatures to outgoing messages. ------------------------------------------------------------------------------ - Mode (in preferred order) ----------- filter - Usage ------------------------------- "scope" "/signature" "-file" "@@FILE" ["-signature" ""] - Remarks ----------------------------- This procedure must be contained in the topmost level filter tab (.tab) since it's supposed to sign outgoing messages and not inbound messages. The config setting 'allow-user-signatutures' determines if signatures are to be applied on a per-user level. In that case the sender's homedir is searched for a signature file. ('domains/localdomain.tld/username/.signature) If found it'll be appended to the outgoing message. Setting 'use-default' determines if the default-signature should be used as an alternative if allow-user-signatutures is set to 0. If use-default is enabled it will apply a default signature to all outgoing messages. Disabling both 'allow-user-signatutures' and 'use-default' will turn off the signing all together. As a third option you can supply a signature file reference with the client call as described above. The 'signature' paramater overrides other config settings. [Scope::status] Generates server statistics on request. ------------------------------------------------------------------------------ - Mode (in preferred order) ----------- cmdalias, mailproc - Usage ------------------------------- "external" "-1" "0" "scope" "/status" ["-from" "@@FROM"] ["-tmpfile" "@@TMPFILE"] - Remarks ----------------------------- The -1 and 0 arguments reflects lo-priority and that XMail don't need to wait for this command to complete. Argument '-tmpfile' must be used infavor of '-from' if you a want to use the 'require-auth' feature. A sample cmdalias tab for this procedure can be found in the extras directory. Open it for instructions (scope-status.tab.cmdalias) This procedure enables you to request a server status/statistics message to be generated and sent out to the "admin" address defined in the Scope main configuration, or optionally an address defined in the procedure config settings ('status-to'). The message contains detailed info about uptime, request and return-code statistics, CPU load etc. Due to the risc of getting your admin mailbox swamped with status messages, this command should only be accessible via a cmdalias, preferrably known only to the XMail administrator. To further stricten access to this procedure, enable 'require-auth' and make sure you authenticate with the username/address defined as Scope administrator when sending a status request. [Scope::vanguard] A pure PERL lightweight virus/worm scanner. ------------------------------------------------------------------------------ - Mode (in preferred order) ----------- filter - Usage ------------------------------- "scope" "/vanguard" "-file" "@@FILE" - Remarks ----------------------------- Returns code 97 (Reject) upon virus positive. Optionally you can enable archiving of infected messages. (See conf.) ! Make sure you got a latest available virus db at hand. Yeah, a pure PERL virus scanner! Scope::vanguard is a lightweight virus scanner utilizing the OpenAntivirus database format, an independent, publically available virus fingerprint database for the open source community. I'd like to point out that vanguard is not the solution if you expect to catch every viruses outthere. If that is your priority, you'd better spill some dollars on a commercial AV product Scope::vanguard focuses on coming down on those frequent ones that appear in your mailbox ever so often. Scope::vanguard help you make it very less so often. The database bundled with Scope::vanguard is a very lightweight version of the Clamav database (a derivate of OAV) and detects worms like Nimda.eml/html Hybris.Gen, Klez, Sircam and the new Bugbear to name but a few of the current ~470 signatures currently present. The vanguard db was assembled with two things in mind; 1) For use in a MTA-context, hunting down and killing worm-type viruses like Klez, Bugbear and others that live and breed on Windooz systems using MUA mechanisms and to spread with SMTP as its primary transport vessel. 2) Performance, perl is perl so you can't expect this thing to be asm-fast. Speed will improve drastically the smaller the virus db gets, so by carefully selecting what signataures the database should contain. With a quality over quantity approach we can still get reasonable good performance with maintained good results detecting the top of the viral-pops. With the vanguard db I managed to gained some ~90% performance improvement compared to using the original OAV database. Scope::vanguard additionally gives you means to put messages containing detected or suspicious viral code into quarantine for later reviewal. These messages are compressed and stored in zip-archives, by default at lib/vanguard/archive. Quarantine archives can further be configured for automated delivery to a moderator once the exceed a defined max-size. This way you never get occational false positive nessages vanishing into oblivion, but can resend these incase they were wrongly rejected for initial delivery. I consider the vanguard.nnn.db (nnn = revision number) database under permanent construction so you are welcome to suggest additions on an ongoing basis. Alternatively, if you find viruses slipping thru Scope::vanguard, you might wanna try the official OAV or preferrably the Clamav virus db, as it's more organized and snap it in as a replacement for vanguard.nnn.db. You will notice slightly better scores in the long run, but to the cost of poorer performance. Better off, once pinpointing the name of the virus you could just borrow the signatare from the OAV/Clamav.db and stick it into vanguard.nnn.db ;) References: http://clamav.elektrapro.com/ http://www.openantivirus.org/ [Scope::access_test] Simple helper-procedure for tuning the access rules. ------------------------------------------------------------------------------ - Mode (in preferred order) ----------- None - Usage ------------------------------- "scope" "/access_test" "-rcpt" "@@RCPT" - Remarks ----------------------------- NOT intended for use in XMail context. This is basically only for testing access rules based on from/rcpt address by running scopefrom the shell/server in debug mode. [Scope::noop] A no-operation procedure. ------------------------------------------------------------------------------ - Mode (in preferred order) ----------- filter, mailproc, custdomains, cmdalias - Usage ------------------------------- "scope" "/noop" - Remarks ----------------------------- As its name implies, a no-operation returning code 96. Suitable for benchmarking, initial testing or temporary redirections.