Contents

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.

Notes / FAQ

• Currently, for 3.1.1+ and 3.2.0, to use any channel for updates requires that updates.spamassassin.org also be used. This is because once the update directory exists, the SpamAssassin modules expect to find all rules in that directory.
  Can plugins be distributed via updates/channels?
  

  indent
  \\ From a technical standpoint, updates can contain plugins. However, the default channel, updates.spamassassin.org, will not publish plugins using this method at this time since people are likely not ready to accept automatic code updates. \\

  
  After sa-update completes, do I have to move the files somewhere for them to be used?
  

  indent
  \\ No. By default, sa-update and the [SpamAssassin] modules use the same location for updates. This means that after a successful update run, the new rules are available for use. As usual, if using spamd, a restart is required for the new rules to be read in and enabled. \\

  
  Should I use "--updatedir" to put updates in the default rules directory (ie: /usr/share/spamassassin), or the site rules directory (ie: /etc/mail/spamassassin)?
  

  indent
  \\ No! Those two directories have specific uses, and attempting to install updates to that directory will likely cripple your [SpamAssassin] installation. This is because when an update is installed, all previous files in the directory are removed first. \\

  
  If I use "--updatedir" to install an update in a subdirectory of my site rules directory (ie: /etc/mail/spamassassin), a number of my local settings (typically set via local.cf) no longer function. Why?
  

  indent
  \\ This can happen if the update channel creates a channel file with a name lexically after the local settings, such as "updates_spamassassin_org.cf". For more information, read the "Using sa-update" section below, and also refer to the man page for "spamassassin". \\

  
  What do I need to do with-respect-to sa-update after a SpamAssassin upgrade?
  

  indent
  \\ Whenever you upgrade the version of [SpamAssassin] that's installed, the directory where the updates are expected to be changes (it's based on the version). So whenever you upgrade, you will want to run sa-update for all of the channels that you want to have installed. \\

  
  After upgrading SpamAssassin several times, there are a number of directories .../3.001001, .../3.001002, .../3.001003, etc. What should I do with them?
  

  indent
  \\ You definitely want to keep the latest version that matches the version of [SpamAssassin] that you have installed. However, the older versions can be removed whenever you like. \\

  
  How often should I run sa-update?
  

  indent
  \\ As often as you like. It typically depends on what time-frame is comfortable for you, and how quickly channels are going to be publishing updates. Generally speaking, once a day is a good starting point. \\

  
  After sa-update was used, the report contact setting becomes @@.
  

  indent
  \\ _This was fixed in 3.1.4._ This issue was tracked in [bug 4862|http://issues.apache.org/SpamAssassin/show_bug.cgi?id=4862]. \\

  
  Can I use sa-update as non-root too?
  

  indent
  \\ Of course. It works just fine as non-root for personal installations. Updates end up in $HOME/var, which is where your [SingleUserUnixInstall] of [SpamAssassin] will look for them. \\

  
  What if I need update requests to go through a proxy server?
  

  indent
  \\ sa-update uses the {{LWP::UserAgent}} module, which allows certain environment variables to be set so that requests use defined proxy servers. The main one of interest is "http_proxy", which should be set to an URL defining the proxy. ie: {{export http_proxy='http://proxy.example.com:8080/'}} \\

  
  

For more information about how to use sa-update and how it works, please read below.

...

Using sa-update

What is sa-update?

...

Simply put, channels are locations where sa-update can download rule and configuration files. By default, sa-update will use the updates.spamassassin.org channel to receive official updates from the SpamAssassin project, but anyone can create a channel and publish updates. By default, sa-update (and spamassassin) expect to find updates in the /var/lib/spamassassin/<spamassassin version> directory, which will have each channel in its own directory underneath. Each channel will also have a channel cf file and (optionally) a channel pre file to load the update's configurations in the update's parent directory. For example:

/var/lib/spamassassin
`-- 3.001001001004
    |-- updates_spamassassin_org
    `-- updates_spamassassin_org.cf

Shows the channel updates.spamassassin.org available for SpamAssassin 3.1.14, underneath the /var/lib/spamassassin directory.

...

$ rm -f channels ; touch channels
$ echo updates.spamassassin.org >> channels
$ echo saupdates.example.com >> channels
$ sa-update --channelfile channels

--checkonly

  Check for update availability, do not install.

  

--allowplugins

  Allow updates to load plugin code (DANGEROUS). You should never enable this for 3rd party update channels, since plugins can execute unrestricted code on your system!

  

--refreshmirrors

  Force the MIRRORED.BY file to be updated.

  

--install <filename>

  Install updates directly from this file. Signature verification will read from filename.asc and filename.sha1 .

  

GPG Related

--(no)gpg:: By default, sa-update will require the use of GPG signatures to verify that downloaded updates are in fact legitimate. However, there may be channels which do not publish GPG signatures, or the system may not have GPG installed. In these situations, specify the

...

$ rm -f gpgkeys ; touch gpgkeys
$ echo 26C900A46DD40CD5AD24F6D7DEE01987265FA05B >> gpgkeys
$ echo 5244EC45 >> gpgkeys
$ sa-update --gpgkeyfile gpgkeys

--import <file>

  Import GPG key(s) from <file> into sa-update's keyring. Use multiple times for multiple files.

  

Other

  *-D, --debug \[area=n,...\]*

  ::	Show debugging information.  This can be useful just to see what sa-update is doing, but is also useful to debug problems, etc.  This option takes the same optional parameter (areasDebugChannels) as the other standard [SpamAssassin] tools.

  

-V, --version:: Display which version of

  Display which version of sa-update is installed.  sa-update is versioned by Subversion revision number as opposed to being tied to a specific [SpamAssassin] version.

  

-v, --verbose

  Be more verbose, like print updated channel names.

  

-h, --help:: Print usage message.

  Print usage message.

  

More information is available via the POD/man page for sa-update.

...

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 / FAQ

...

\\
   From a technical standpoint, updates can contain plugins.  However, the default channel, updates.spamassassin.org, will not publish plugins using this method at this time since people are likely not ready to accept automatic code updates.
\\
 

...

\\
   No.  By default, sa-update and the [SpamAssassin] modules use the same location for updates.  This means that after a successful update run, the new rules are available for use.  As usual, if using spamd, a restart is required for the new rules to be read in and enabled.
\\
 

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 update checks from clients, a lightweight method (DNS queries) is used to specify what update version is the latest for any given version of SpamAssassin. sa-update also uses a 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 makes a DNS TXT query for <version>.<channel>. ie: Running 3.1.1's sa-update, the default updates.spamassassin.org channel causes a DNS lookup for 1.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 a DNS TXT record mirrors.<channel>).

Summary

DNS Records:

...

 mirrors.updates.spamassassin.org TXT "http://spamassassin.apache.org/updates/MIRRORED.BY" 

...

 *.1.3.updates.spamassassin.org TXT "386156" 

Mirrors file:

...

 http://buildbot.spamassassin.org.nyud.net:8090/updatestage/ 

Update file:

...

 sha1sum UPDATE_NUMBER.tar.gz 

...

Installed Updates

When updates are downloaded, they are put into a directory under the local state dir (default /var/lib/spamassassin/<spamassassin version>) similar to:

/var/lib/spamassassin
`-- 3.001004
    |-- updates_spamassassin_org
    `-- updates_spamassassin_org.cf

The files from the update go into updates_spamassassin_org, and the *.cf files are then included by updates_spamassassin_org.cf, which also keeps track of what update version is installed. Therefore, if it is desired to change the update directory, the .cf and the update directory will exist there.

Publishing channels for sa-update

See PublishingRuleUpdates.

SARE Channels

Unfortunately the SARE ruleset has been discontinued in 2009. (Historical details of various channels from SARE can be seen at SareChannels)

The Backend

Details of the rule-update generation backend at updates.spamassassin.org can be read at SaUpdateBackend.

...

 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