3.2 Modifying the Score of a Test

You may find some tests more indicative of spam than SpamAssassin does by default. If SpamAssassin already provides a test that you value but doesn't assign it a high enough score (higher scores are more indicative of spam), you can easily modify the score of the test. Similarly, if one of SpamAssassin's tests is giving you too many false positives, you can reduce its score or disable the test entirely by setting its score to 0. SpamAssassin will not attempt to run a test with a score of 0.

3.2.1 Modifying Scores Systemwide

Make systemwide score adjustments in the systemwide configuration file, typically /etc/mail/spamassassin/local.cf . To modify the score of a test, you must first determine its test name , either by reading the ruleset files or by examining the spam report from a message. To get a spam report on a message that doesn't score high enough for SpamAssassin to generate a report, you can use spamassassin --test-mode , as described in Chapter 2.

To change the score of a test, simply add a new score directive to the configuration file, like this:

 score HTML_WIN_OPEN 2 

This will enable the HTML_WIN_OPEN test and add two points to the score of messages that test positive on this test.

You can use the same approach to modify the descriptions of tests by adding new describe directives. For example, the default description for the HOT_NASTY test is "Possible porn - Hot, Nasty, Wild, Young". To shorten that to "Possible porn", add this directive to the configuration file:

 describe HOT_NASTY Possible porn 

3.2.2 Modifying Scores on a Per- User Basis

Users can use the score directive in per-user preference files to change the scoring of a test for an individual user. To do so, a user edits the .spamassassin/user_prefs file in her home directory and adds score directives. This approach to customizing scores is the simplest, but it requires users to have accounts on the system and access to files in their accounts.

3.2.3 Storing Scores in an SQL Database

When users do not have accounts or shell access (e.g., on a system that is an IMAP or webmail server), per-user scores can be stored in an SQL database and spamd can be configured to look up scores in the database. To store scores in SQL, you must install the DBI Perl module and an appropriate driver module for your SQL database server. Common choices are DBD-mysql (for the MySQL server), DBD-Pg (for the PostgreSQL server), and DBD-ODBC (for connection to an ODBC-compliant server). ^[1]

^[1] "ODBC" stands for Open Database Connectivity.

You should create a database and a user with privileges to access it. You must then create a table in the database to store the user scores. The SpamAssassin source code includes a schema for a MySQL table in the sql subdirectory, which is shown in Example 3-2. SpamAssassin 3.0 also includes a schema for a PostgreSQL table.

Example 3-2. A MySQL table for user scores

 CREATE TABLE userpref (   username varchar(100) NOT NULL,   preference varchar(30) NOT NULL,   value varchar(100) NOT NULL,   prefid int(11) NOT NULL auto_increment,   PRIMARY KEY (prefid),   INDEX (username) ) TYPE=MyISAM; 

You can use a different name for the table. The name given in Example 3-2 is the default, however, and using it will require the least amount of SpamAssassin configuration effort.

Each row in this table specifies the score for a single test for an individual user. SpamAssassin expects the columns to contain the following information:

username

Gives the username or email address of the user (the latter is more useful in virtual hosting environments). The special username @GLOBAL can be used to define global values in SQL that will be applied to all users.

preference

Gives the name of the test to modify the score of. The column can also be used with other directives (e.g., required_hits , auto_report_threshold , and the whitelisting and blacklisting directives described later in this chapter) but cannot define new rules or modify administrative settings.

value

Gives the new score for the test or a new value for one of the other directives (e.g., number of hits required to call a message spam or an email address to add to the whitelist). SpamAssassin does not provide any tools for adding data to these tables.

The prefid column and the PRIMARY KEY and INDEX clauses are useful but not necessary. prefid defines a primary key for the table, and an index is built on the username column to speed up queries.

To configure SQL support for user scores, set the following configuration parameters in your systemwide configuration file ( local.cf ):

user_scores_dsn DSN

This directive defines the data source name (DSN) for the SQL database. It tells spamd how it will connect to the database server. A typical DSN, for the Perl DBI module, is written like this:

 DBI:   databasetype:databasename:hostname:port   

For example, to use a MySQL database named sascores running on a database server on the SpamAssassin host, the DSN would read:

 DBI:mysql:sascores:localhost:3306 

If the server were running PostgreSQL, the DSN would read:

 dbi:Pg:dbname=sascores;host=localhost;port=5432; 

user_scores_sql_username username

This directive defines the username that will be used to connect to the database server. This user must have permission to issue SELECT queries against the table but need not be permitted to modify the data or database structure.

user_scores_sql_password password

This directive defines the password associated with the username that will be used to connect to the server.

user_scores_sql_table tablename

This directive defines the name of the table that contains user preferences. The default tablename is "userpref".

user_scores_sql_custom_query query (SpamAssassin 3.0)

This directive specifies the SQL query that SpamAssassin will use to look up user preferences. The query must be specified on a single (long) line in the configuration file. The default query is:

 SELECT preference, value FROM _TABLE_ WHERE username = _USERNAME_ OR username = '@GLOBAL' ORDER BY username ASC 

This is read as "return the preference and value fields from the configured table (_TABLE_) for those rows with the specified username (_USERNAME_) or with the @GLOBAL username, in ascending lexicographic order." Because SpamAssassin will use the value of each matching preference it encounters in order, and because @GLOBAL sorts before all usernames, user-specific preferences will effectively override global preferences.

You can use this directive to construct your own custom queries. Custom queries must also return the preference and value columns (in that order). Queries may use the special symbols _TABLE_ ( replaced by the name of the table where user preferences are stored), _USERNAME_ (replaced by the user's username), _MAILBOX_ (replaced by the portion of the username before an at sign [ @ ] or the whole username if there is no at sign), and _DOMAIN_ (replaced by the portion of the username after an at sign or a null value if there is none). The manpage for Mail::SpamAssassin::Conf provides a few interesting examples of default queries. To support individual, domain, and global settings, add rows to the table with usernames of @~ domain (which will sort after @GLOBAL but before real usernames) and use this query:

 SELECT preference, value FROM _TABLE_ WHERE username = _USERNAME_ OR username = '@GLOBAL'  OR username = '@~'_DOMAIN_ ORDER BY username ASC 

If you prefer to have some global preferences that cannot be overridden by users and others that can, you can add rows to the table for the unchangeable preferences with username ~GLOBAL (which will sort after all usernames) and rows for the changeable preferences with username @GLOBAL and use this query:

 SELECT preference, value FROM _TABLE_ WHERE username = _USERNAME_ OR username = '@GLOBAL'  OR username = '~GLOBAL' ORDER BY username ASC 

Finally, you'll need to start spamd with the --nouser-config command-line option and either the --sql-config or --setuid-with-sql option to enable SQL-based configuration (and disable the use of ~/.spamassassin/user_prefs files, which cannot be used by spamd together with SQL). If spamd runs as a non- root user, or if your users don't have home directories, use --sql-config ; if spamd runs as root and users have home directories, using --setuid-with-sql will enable spamd 's usual practice of changing uid to the user running spamc so that it can access the user's autowhitelist files.

3.2.4 Storing Scores in an LDAP Database

Another way to store per-user preferences in SpamAssassin 3.0 is in an LDAP (Lightweight Directory Access Protocol) database. This approach may appeal particularly to sites that already store their user account configuration in LDAP. To store scores in LDAP, you must install the Net::LDAP and URI Perl modules.

LDAP objects (like those that represent users) and their attributes (such as username, password, email address, etc.) are defined by one or more LDAP schemas . To add SpamAssassin preferences to your users, extend the objectClass that represents a user to allow an additional, optional spamassassin attribute, which you should define like this:

 # spamassassin   # see http://SpamAssassin.org/ .   attributetype ( 2.16.840.1.113730.3.1.217           NAME 'spamassassin'           DESC 'SpamAssassin user preferences settings'           EQUALITY caseExactMatch           SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) 

The attribute SYNTAX must be multivalued (as in the example, which specifies the DirectoryString syntax with object identifier (OID) 1.3.6.1.4.1.1466.115.121.1.15), because a user object will have multiple spamassassin attributes, one for each preference setting.

The attributes themselves should be stored in the database. A spamassassin LDAP attribute should be set to the name of a SpamAssassin configuration directive followed by the value for the directive, separated by a space. SpamAssassin 3.0 includes an example of what such user definitions might look like in LDIF (LDAP Interchange Format) format. The spamassassin attribute added to this user's LDAP entry is emphasized :

 dn: cn=Curley Anderson,ou=MemberGroupB,o=stooges ou: MemberGroupB o: stooges cn: Curley Anderson objectClass: top objectClass: person objectClass: organizationalPerson objectClass: inetOrgPerson mail: [e-mail] givenname: Curley sn: Anderson uid: curley initials: Joe homePostalAddress: 14 Cherry Ln.$Plano TX 78888 postalAddress: 15 Fitzhugh Ave.  spamassassin: add_header all Foo LDAP read  l: Dallas st: TX postalcode: 76888 pager: 800-555-1319 homePhone: 800-555-1313 telephoneNumber: [phone] mobile: [phone] title: Developemnt Engineer facsimileTelephoneNumber: 800-555-3318 userPassword: curleysecret 

To configure LDAP support for user scores, set the following configuration parameters in your systemwide configuration file ( local.cf ):

user_scores_dsn DSN

Defines the data source name for the LDAP database. It tells spamd how it will connect to the LDAP server. LDAP DSNs are specified as URLs according to RFC 2255, like this:

 ldap://host:port/basedn?attr?scope?filter 

For example, to use the LDAP server on the SpamAssassin host to search for objects under the base DN of dc=example,dc=com and to return the spamassassin attributes for those in which the uid attribute matches the username that SpamAssassin is running for, the DSN would be:

 ldap://localhost:389/dc=example,dc=com?spamassassin?sub?uid=_  _USERNAME_  _ 

user_scores_ldap_username bind_dn

Provides the DN that SpamAssassin should use to bind to the LDAP server. This DN must have sufficient privileges to perform the query defined in the DSN.

user_scores_ldap_password password

Provides the password that SpamAssassin should use to authenticate itself when binding to the LDAP server with the specified bind_dn .

Finally, you'll need to start spamd with the --nouser-config command-line option and either the --ldap-config or --setuid-with-ldap option to enable LDAP-based configuration (and disable the use of ~/.spamassassin/user_prefs files, which cannot be used by spamd together with LDAP). If spamd runs as a non- root user, or if your users don't have home directories, use --ldap-config ; if spamd runs as root and users have home directories, using --setuid-with-ldap will enable spamd 's usual practice of changing uid to the user running spamc so that it can access the user's autowhitelist files.