You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 3 Next »

Note: This page is under construction and shouldn't be considered "complete". If there are any questions, etc, please feel free to contact the users at spamassassin.apache.org list for more information.

Why sa-update?

The goal of sa-update is to download new configuration files (rules, scores, etc,) so that SpamAssassin will use them to better catch spam and/or to avoid catching ham messages. The main reason to use sa-update is that the old method of disseminating rules (a new SpamAssassin release) is a lengthy process that can take months. Spam is rapidly changing, and new rules are often written in response. With sa-update, those rules can quickly (potentially within minutes) be distributed and the new spam caught. sa-update allows rules to be distributed as they are developed, while full SpamAssassin releases can focus on bug fixes and new features.

Channels

sa-update commandline

Examples

sa-update && service spamassassin restart

This is potentially the most simple example of using sa-update. It will see if an update is available, and download the update and lint-test it as necessary. If there was an update and no problems were detected, sa-update returns 0 and the 

 service spamassassin restart

command is run (used on Linux machines to restart the spamassassin service (spamd)).

sa-update -D

If there is a problem with doing updates, or just some curiousity about what is happening, run sa-update in debug mode and it will show you what it is doing step-by-step.

sa-update -D --updatedir /tmp/updates

To perform updates without attempting to put the files into the system-wide location (either for users or to test, etc,) use the --updatedir option to aim at a different directory for which to put the updates.

Additonal Notes

  • From a technical standpoint, updates can also contain plugins. However, the default channel, updates.spamassassin.org, will not publish plugins using this method at this time.
  • Currently, for 3.1.1 and 3.2.0, to use any channel for updates requires that updates.spamassassin.org also be used.

Publishing channels for sa-update

Channels are fairly simple to setup and use. Simply put, updates are files contained in a standard tar.gz archive, distributed via HTTP. To allow for frequent requests from clients, a lightweight announcement method is used by generating certain DNS records which specify what update is available for a given version of SpamAssassin. sa-update also uses a published mirror file which lists all of the URLs where the update can be downloaded from, optionally including weights for different mirrors.

How does it work?

When looking for an update, sa-update reverses the version and queries for <version>.<channel>. ie: Running 3.1.0's sa-update, the default updates.spamassassin.org channel causes a DNS lookup for 0.1.3.updates.spamassassin.org. The query is for a TXT record containing the update number, which should be a monotonically increasing value. Assuming an update is necessary, sa-update will then read the MIRRORED.BY file (downloading it first if necessary from the URL found in mirrors.<channel>). Then the

Summary

DNS Records:

  • mirrors.<channel> TXT "http://URL/TO/MIRRORS/FILE" 
     mirrors.updates.spamassassin.org TXT "http://spamassassin.apache.org/updates/MIRRORED.BY"
  • <version>.<channel> TXT "UPDATE_NUMBER" 
     *.1.3.updates.spamassassin.org TXT "386156"

Mirrors file:

  • List of URLs which contain the updates 
     http://buildbot.spamassassin.org.nyud.net:8090/updatestage/

Update file:

  • Only files (no directories) contained in a tar.gz archive file named UPDATE_NUMBER.tar.gz
  • A sha1sum file named UPDATE_NUMBER.tar.gz.sha1 with the output of 
     sha1sum UPDATE_NUMBER.tar.gz
    .
  • Recommended, but optional, a detached GPG signature for the update named UPDATE_NUMBER.tar.gz.asc via something like 
     gpg -bas UPDATE_NUMBER.tar.gz

Examples

Here is a short example of how an update for SpamAssassin 3.1.x would be published. By convention, we use the svn version of the directory as the update number.

$ svnversion
386156
$ ls -al
total 528
drwxr-xr-x  3 felicity fame  4096 Mar 14 13:10 .
drwxr-xr-x  4 felicity fame    27 Feb 19 14:55 ..
-rw-r--r--  1 felicity fame  5479 Feb 19 14:55 10_misc.cf
-rw-r--r--  1 felicity fame  8112 Mar 13 02:49 20_advance_fee.cf
-rw-r--r--  1 felicity fame  1602 Feb 19 14:55 20_anti_ratware.cf
-rw-r--r--  1 felicity fame  6690 Mar 13 02:49 20_body_tests.cf
-rw-r--r--  1 felicity fame  1534 Mar 13 02:49 20_compensate.cf
[...]
-rw-r--r--  1 felicity fame 33266 Mar 11 18:13 50_scores.cf
-rw-r--r--  1 felicity fame  8564 Mar 14 13:10 80_additional.cf
$ tar -cf 386156.tar *.cf
$ ls -la 386156.tar 
-rw-r--r--  1 felicity fame 471040 Mar 15 15:37 386156.tar
$ gzip -9v 386156.tar 
386156.tar:      74.1% -- replaced with 386156.tar.gz
$ ls -la 386156.tar.gz 
-rw-r--r--  1 felicity fame 122206 Mar 15 15:37 386156.tar.gz
$ mv 386156.tar.gz /www/spamassassin/updates
$ vi /var/named/updates.spamassassin.org
[increase serial number, add in new update line '*.1.3 TXT "386156"']
$ rndc reload
  • What if I want to publish updates for some versions but not others?

The answer is pretty simple and comes down to DNS records. As long as the reverse version DNS request does not return a TXT record, sa-update will consider there to be no updates available. ie: if we want to publish update 386156 for SpamAssassin 3.1.x, but not 3.1.0, we could use the following records:

0.1.3 A   127.0.0.1
*.1.3 TXT "386156"

When v3.1.0's sa-update looks for an update, it gets no TXT response (having an existing 0.1.3 record overrides the wildcard record), and therefore it sees no updates available. However, when v3.1.1 or above looks for an update, it gets "386156" returned.

TheoVanDinter

  • No labels