QSF(1)

📦 version 1.2.23, in fedora 43, fedora 44

💖 QSF(1) — the qsf girlies' guide 💖

User Commands ✨ spam filter edition

okay so bestie, welcome to qsf, aka the quick spam filter 🎀 she's a little Unix program who reads your email and is like "hmm. this is giving spam." and does something about it. let's get into it 💅

✨ NAME ✨

qsf — quick spam filter 🦋

✨ SYNOPSIS ✨

Filtering:

qsf [-snrAtav] [-d DB] [-g DB] [-L LVL] [-S SUBJ] [-H MARK]
[-Q NUM] [-X NUM]

Training:

qsf -T SPAM NONSPAM [MAXROUNDS] [-d DB]

Retraining:

qsf -[m|M] [-d DB] [-w WEIGHT] [-ayN]

Database:

qsf -[p|D|R|O] [-d DB]

Database merge:

qsf -E OTHERDB [-d DB]

Allow-list query:

qsf -e EMAIL [-m|-M|-t] [-d DB] [-g DB]

Deny-list query:

qsf -y -e EMAIL [-m -m|-M -M|-t] [-d DB] [-g DB]

Help: qsf -[h|V]

✨ DESCRIPTION ✨

so here's the vibe: qsf reads a single email on standard input, and by default outputs it on standard output 💌 like, it's not out here being dramatic, it just passes your mail through. BUT. if the email is determined to be spam, an additional header (X-Spam: YES) gets added, and optionally the subject line can have [SPAM] prepended to it 🚨 periodt.

qsf is intended to be used in a procmail(1) recipe, in a ruleset such as this:

:0 wf
| qsf -ra

:0 H:
* X-Spam: YES
$HOME/mail/spam

for more examples, including sample procmail(1) recipes, see the EXAMPLES section below 👀

🎀 Training 🎀

before qsf can be used properly, she needs to be trained. no cap, she doesn't just know things, she has to learn. a good way to train qsf is to collect a copy of all your email into two folders — one for spam, and one for non-spam 🗂️ once you have done this, you can use the training function, like this:

qsf -aT spam-folder non-spam-folder

this will generate a database that qsf can use to guess whether email received in the future is spam or not 🔮 note that this initial training run may take a long time, but you should only need to do it once. slay.

to mark a single message as spam, pipe it to qsf with the --mark-spam or -m ("mark as spam") option 💀 this will update the database accordingly and discard the email.

to mark a single message as non-spam, pipe it to qsf with the --mark-nonspam or -M ("mark as non-spam") option 🫶 again, this will discard the email.

if a message has been mis-tagged, send it to qsf as the opposite type. for example, if it has been mistakenly tagged as spam, pipe it into qsf --mark-nonspam --weight=2 to add it to the non-spam side of the database with double the usual weighting 💪

🎀 The allow-list 🎀

a feature called the "allow-list" can be switched on by specifying the --allowlist or -a option ✨ with the allow-list, messages' From: and Return-Path: addresses are checked against a list of people you have said to allow all messages from, and if a message matches, it is never marked as spam 🥰 this means you can add all your friends to the allow-list and qsf will then never mis-file their messages. bestie protection squad fr fr.

a quick way to add everyone is to use the -a option with -T 🌈 everyone in your non-spam folder who has sent you an email will be added to the allow-list automatically during training. iconic behaviour, no notes.

you can manually add and remove addresses to and from the allow-list using the -e (email) option ✉️ for examples, see the EXAMPLES section.

in general, you probably always want to enable the allow-list, so always specify the -a option when using qsf 👑 this will automatically maintain the allow-list based on what you classify as spam or non-spam.

the only times you might want to turn it off are when people on your allow-list are prone to getting viruses 🦠 or if a virus is causing email to be sent to you that is pretending to be from someone on your allow-list. like, catfish but for email. rude.

🎀 Backup and restore 🎀

because the database format is platform-specific, it is a good idea to periodically dump the database to a text file using qsf -D so that, if necessary, it can be transferred to another machine and restored with qsf -R later on 💾

note that since the actual contents of email messages are never stored in the database (see the "Technical details" sub-section), you can safely share your qsf database with others, by sending them a text dump which they can restore into their own database 🫂 sharing is caring.

✨ OPTIONS ✨

the qsf options are listed below 💅

🎀 Database selection options 🎀

  • -d, --database [TYPE:]FILE — use FILE as the spam/non-spam database. the default is to use /var/lib/qsfdb and, if that is not available or is read-only, $HOME/.qsfdb. this option can also be useful if there is a system-wide database but you do not want to use it — specifying your own here will override the default.

if you prefix the filename with a TYPE, of the form btree:$HOME/.qsfdb, then this will specify what kind of database FILE is, such as list, btree, gdbm, sqlite and so on 🔍

check the output of qsf -V to see which database backends are available. the default is to auto-detect the type, or, if the file does not already exist, use list.

note that TYPE is not case-sensitive.

  • -g, --global [TYPE:]FILE — use FILE as the default global database, instead of /var/lib/qsfdb. if you also specify a database with -d, then this "global" database will be used in read-only mode in conjunction with the read-write database specified with -d.

the -g option can be used a second time to specify a third database, which will also be used in read-only mode.

as with -d, the filename can optionally be prefixed with a TYPE which specifies the database type.

🎀 Filtering options 🎀

  • -s, --subject — rewrite the Subject line of any email that turns out to be spam, adding [SPAM] to the start of the line 🚩
  • -S, --subject-marker SUBJECT — instead of adding [SPAM], add SUBJECT to the start of the Subject line of any email that turns out to be spam. implies -s ✍️
  • -H, --header-marker MARK — instead of setting the X-Spam header to YES, set it to MARK if email turns out to be spam. this can be useful if your email client can only search all headers for a string, rather than one particular header (so searching for YES might match more than just the output of qsf) 🔎
  • -n, --no-header — do not add an X-Spam header to messages 🚫
  • -r, --add-rating — insert an additional header X-Spam-Rating which is a rating of the "spamminess" of a message from 0 to 100; 90 and above are counted as spam, anything under 90 is not considered spam 📊 if combined with -t, then the rating (0-100) will be output, on its own, on standard output.
  • -A, --asterisk — insert an additional header X-Spam-Level which will contain between 0 and 20 asterisks (*), depending on the spam rating ⭐⭐⭐
  • -v, --verbose — add extra X-QSF-Info headers to any filtered email, containing error messages and so on if applicable 🗣️ specify -v more than once to increase verbosity.

🎀 Classification and behavioural options 🎀

  • -L, --level, --threshold LEVEL — change the spam scoring threshold level which must be reached before an email is classified as spam. the default is 90 📈
  • -a, --allowlist — enable the allow-list 💖 this causes the email addresses given in the message's From: and Return-Path: headers to be checked against a list; if either one matches, then the message is always treated as non-spam, regardless of what the token database says.

when specified with a retraining flag, -a -m (mark as spam) will remove that address from the allow-list as well as marking the message as spam, and -a -M (mark as non-spam) will add that address to the allow-list as well as marking the message as non-spam.

the idea is that you add all of your friends to the allow-list, and then none of their messages ever get marked as spam 🫶 besties stay winning.

  • -y, --denylist — enable the deny-list 😤 this causes the email addresses given in the message's From: and Return-Path: headers to be checked against a second list; if either one matches, then the message is always treated as spam.

training works in the same way as with -a, except that you must specify -m or -M twice to modify the deny-list instead of the allow-list, and with the reverse syntax: -y -m -m (mark as spam) will add that address to the deny-list, whereas -y -M -M (mark as non-spam) will remove that address from the deny-list. this double specification is so that the usual retraining process never touches the deny-list; the deny-list should be carefully maintained rather than automatically generated 🧐

normally you would not need to use the deny-list.

  • -Q, --min-tokens NUM — only give a score if more than NUM tokens are found in the message — otherwise the message is assumed to be non-spam, and it is not modified in any way. the default is 0 🔢 this option might be useful if you find that very short messages are being frequently miscategorised.
  • -t, --test — instead of passing the message out on standard output, output nothing, and exit 0 if the message is not spam, or exit 1 if the message is spam 🧪 if combined with -r, then the spam rating will be output on standard output.
  • -e, --email, --email-only EMAIL — query or update the allow-list entry for the email address EMAIL 📧 with no other options, this will simply output YES if EMAIL is in the allow-list, or NO if it is not.

with -t, it will not output anything, but will exit 0 (success) if EMAIL is in the allow-list, or 1 (failure) if it is not.

with the -m (mark-spam) option, any previous allow-list entry for EMAIL will be removed.

with the the -M (mark-nonspam) option, EMAIL will be added to the allow-list if it is not already on it 🫶

if EMAIL is just the word MSG on its own, then an email will be read from standard input, and the email addresses given in the From: and Return-Path: headers will be used.

using -e automatically switches on -a ✨

if you also specify -y, then the deny-list will be operated on. remember that -m and -M are reversed with the deny-list 😵💫

if you specify an email address of the form @domain (nothing before the @), then the whole domain will be allow or deny listed 🌐

🎀 Training options 🎀

  • -m, --mark-spam — instead of passing the message out on standard output, mark its contents as spam and update the database accordingly 💀 if the allow-list (-a) is enabled, the message's From: and Return-Path: addresses are removed from the allow-list.

okay so real quick, still on the -m tip: if the deny-list (-y) is on and you hit -m twice, the message's addresses get added to the deny-list instead. 💅

  • -M, --mark-nonspam — instead of pushing the message out on standard output, this marks its contents as non-spam and updates the database accordingly. If the allow-list (-a) is enabled, the message's “From:” and “Return-Path:” addresses get added to the allow-list (peep the -a option above bestie). And if the deny-list (-y) is enabled and you specify -M twice, the message's addresses get removed from the deny-list instead. 🫶
  • -w, --weight WEIGHT — when you're marking something as spam or non-spam, this updates the database with a weighting of WEIGHT per token instead of the default of 1. So good for fixing mistakes — like, a message that got wrongly detected as spam should be marked as non-spam with a weighting of 2, i.e. double the usual weighting, to counteract the error. 🔥
  • -T, --train SPAM NONSPAM [MAXROUNDS] — trains the database using the two mbox folders SPAM and NONSPAM, by testing every message in each folder and updating the database each time a message gets miscategorised. This runs several times, and yeah it may take a while to run. Pass the -a (allow-list) flag to add every sender in the NONSPAM folder to your allow-list as a side-effect of the training process. 🎀

If MAXROUNDS is specified, training will end after this number of rounds if the results are still not good enough. The default is a maximum of 200 rounds.

💾 Database management options 💾

  • -D, --dump [FILE] — dumps the contents of the database as a platform-independent text file, which is giving archival, transfer-to-another-machine, all of that. The data goes out on stdout, or into the given FILE. 📦
  • -R, --restore [FILE] — rebuilds the database from scratch from the text file on stdin. If a FILE is given, data is read from there instead of from stdin. 🌱
  • -E, --merge OTHERDB — merges the OTHERDB database into the current database. Super useful if you wanna take one user's database and merge it into the system-wide one, for instance (this would be done by, as root, doing qsf -d /var/lib/qsfdb -E /home/user/.qsfdb and then removing /home/user/.qsfdb). 🫱🫲
  • -P, --plain-map FILE — maintains a mapping of all database tokens to their non-hashed counterparts in FILE, one token per line. This can be useful if you wanna be able to list the contents of your database at a later date, for instance to get a list of email addresses in your allow-list. Note that using this option may slow qsf down, and only entries written to the database while this option is active will be stored in FILE. ⚠️

✨ Miscellaneous options ✨

  • -O, --tokens — instead of filtering, this outputs a list of the tokens found in the message read from standard input, along with the number of times each token was found. Only useful if you wanna use qsf as a general tokeniser for use with another filtering package. 🔍
  • -B, --benchmark SPAM NONSPAM [MAXROUNDS] — benchmarks the training process using the two mbox folders SPAM and NONSPAM. A temporary database is created and trained using the first 75% of the messages in each folder, and then the entire contents of each folder is tested to see how many false positives and false negatives occur. The temporary database is removed afterwards. Some timing information is also displayed. ⏱️

This can be used to decide which backend is best on your system. Use -d to select a backend. For example, qsf -B spam nonspam -d GDBM.

The exception to this is the MySQL backend, where a full database specification must be given, of the form -d MySQL:database=db;host=localhost;..., and the database table given will not be wiped beforehand or dropped afterwards.

As with -T, if MAXROUNDS is specified, training will never be done for more than this number of rounds; the default is 200.

  • -h, --help — prints a usage message on standard output and exits successfully. 🫶
  • -V, --version — prints version information, including a list of available database backends, on standard output and exits successfully. 👑

🦕 Deprecated options 🦕

The following options are only for use with the old binary tree database backend or old databases that haven't been upgraded to the new format that came in with version 1.1.0. (iykyk, but also like… upgrade bestie 💀)

  • -N, --no-autoprune — when marking as spam or nonspam, never automatically prune the database. Usually the database is pruned after every 500 marks; if you would rather --prune manually, use -N to disable automatic pruning. ✂️
  • -p, --prune — removes redundant entries from the database and cleans it up a little. This is automatically done after several calls to --mark-spam or --mark-nonspam, and during training with --train if the training takes a large number of rounds, so it should rarely be necessary to use --prune manually unless you are using -N/--no-autoprune. 🧹
  • -X, --prune-max NUM — when the database is being pruned, no more than NUM entries will be considered for removal. This is to prevent CPU and memory resources being taken over. The default is 100,000, but in some circumstances (if you find that pruning takes too long) this option may be used to reduce it to a more manageable number. 🧮

📁 FILES 📁

  • /var/lib/qsfdb — the default (system-wide) spam database. If you wanna install qsf system-wide, this should be read-only to everyone; there should be one user with write access who can update the spam database with qsf --mark-spam and qsf --mark-nonspam when necessary. 🔒
  • /var/lib/qsfdb2 — a second, read-only, system-wide database. This can be useful when installing qsf system-wide and using third-party spam databases; the first global database can be updated with system-specific changes, and this second database can be periodically updated when the third-party spam database is updated. 🌈
  • $HOME/.qsfdb — the default spam database for per-user data. Users without write access to the system-wide database will have their data written here, and the two databases will be read together. The per-user database will be given a weighting equivalent to 10 times the weighting of the global database. 💜

📝 NOTES 📝

Currently, you cannot use qsf to check for spam while the database is being updated. This means that while an update is in progress, all email is passed through as non-spam. 😭

There is an upper size limit of 512Kb on incoming email; anything larger than this is just passed through as non-spam, to avoid tying up machine resources.

The plaintext token mapping maintained by --plain-map will never shrink, only grow. It is intended for use by housekeeping and user interface scripts that, for instance, the user can use to list all email addresses on their allow-list. These scripts should take care of weeding out entries for tokens that are no longer in the database. If you have no such scripts, there is probably no point in using --plain-map anyway.

Avoid using the deny-list (-y) in any automated retraining, as it can cause the filter to reject mail unnecessarily. In general the deny-list is probably best left unused unless explicitly required by your particular setup. 🚫

If both the allow-list and the deny-list are enabled, then email addresses will first be checked against the deny-list, then the allow-list, then the domain of the email address will be checked for matching @domain entries in the deny-list and then in the allow-list. 📋

🐛 BUGS 🐛

If you have problems with qsf, please check the list below; if this does not help, refer to the REPORTING BUGS section. 🫂

💀 Nothing is being marked as spam.

First, use the -r option to switch on the “X-Spam-Rating” header, and check that this header appears in email passed through qsf. If it does not, then it is likely that qsf is not being run at all — check your configuration of procmail(1) or its equivalent.

If you are seeing “X-Spam-Rating” headers, and different emails have different scores, then you may simply need to retrain your database a little more. Take more spam email and pass it to qsf -m.

If you are seeing “X-Spam-Rating” headers but they all give the same spam rating, then the most likely reason is that qsf is not reading any database. Make sure that whatever is processing the email has read permissions on /var/lib/qsfdb and/or ~/.qsfdb — and make sure that, if you are using ~/.qsfdb, what your database creator thought was ~ ($HOME) is the same as it is for whatever is processing the email. 🙈

😴 Retraining sometimes takes a very long time.

With the obtree backend or 2-column MySQL or SQLite tables, every 500th retrain (-m or -M), the database is pruned. On some systems this may take some time, and during this time the database is locked (except when using the MySQL or SQLite backends). If you constantly do a lot of retraining and want to avoid this, then use the -N option to suppress auto-pruning, and then have a cron(8) job or something run a manual prune (qsf -p) every now and again. ⏳

😵 Running qsf from procmail fails with an error.

If you can run qsf from the command line, but in your procmail log file you get errors about qsf: cannot execute binary file, then contact your system administrator for help. It may be that incoming email is handled by a different server to the one you normally shell into, and either they are of a different architecture or operating system, or the mail server is not permitted to execute user-owned binaries. 🧚

✨ EXAMPLES ✨

Okay bestie, this is the part where it gets fun. Like, actually useful. Real recipes, copy-paste energy, no cap. 💖

🎀 Filtering ALL your mail through qsf

Want every single message to go through qsf, with the allow-list turned on and the "spam rating" header getting added? Slap this into your .procmailrc file:

:0 wf
| qsf -ra

And if you want qsf to also yeet a literal “[SPAM]” onto the subject line of anything it clocks as spam? Do this instead, queen:

:0 wf
| qsf -sra

🌸 Managing your allow-list (it's giving admin privileges)

Add “foo@bar.com” to your allow-list:

qsf -e foo@bar.com -M

Remove “bad@nasty.com” from your allow-list (bye girl 👋):

qsf -e bad@nasty.com -m

And to check whether “someone@somewhere.com” is in the allow-list or not:

qsf -e someone@somewhere.com

💅 The spambox@yourdomain.com situation

Say you wanna auto-mark anything sent to spambox@yourdomain.com as spam. Here's the "naive" version — works, but it's lowkey a little reckless:

:0 H
* ^To:.*spambox@yourdomain.com
| qsf -am

Now here's the clever version. Same goal, except it only marks mail to spambox@yourdomain.com as spam in the database if qsf does NOT already think it's spam. Why? Because it stops the database from getting too heavily weighted. Iconic behavior tbh:

# If sent to spambox@yourdomain.com:
:0
* ^To:.*spambox@yourdomain.com
{
    :0 wf
    | qsf -a

    # The above two lines can be skipped if you've
    # already piped the message through qsf.

    # If the qsf database says it's not spam,
    # mark it as spam!
    :0 H
    * ^X-Spam: NO
    | qsf -am
}
Pro tip from the original, not me: remove the -a option in the above examples if you don't want to use the allow-list. 💖

🦋 The "your (something) is on fire" filter

A more complicated filtering example — this one only runs qsf on messages that don't have a subject line saying “your (something) is on fire” AND that don't have a sender address ending in “@foobar.com”. Meaning: messages with that subject line OR that sender address will NEVER be marked as spam, no matter what. Periodt.

:0 wf
* ! ^Subject: Your .* is on fire
* ! ^From: .*@foobar.com
| qsf -ra

For more on procmail(1) recipes, go read the procmailrc(5) and procmailex(5) manual pages. 📚

💜 mutt macros (iykyk)

A couple of macros to drop into your .muttrc file if you use mutt(1) as your mail user agent:

# Press F5 to mark a message as spam and delete it
macro index <f5> "<pipe-message>qsf -am\n<delete-message>"
macro pager <f5> "<pipe-message>qsf -am\n<delete-message>"

# Press F9 to mark a message as non-spam
macro index <f9> "<pipe-message>qsf -aM\n"
macro pager <f9> "<pipe-message>qsf -aM\n"

Again — remove the -a option in the above examples if you don't wanna use the allow-list. Same deal as before.

⚠️ Heads up bestie: the above macros won't work when you're operating on multiple tagged messages. For that you'd need something like this:
macro index <f5> ":set pipe_split\n<tag-prefix><pipe-message>qsf
-am\n<tag-prefix><delete-message>\n:unset pipe_split\n"

🌈 qmail setup

If you use qmail(7), then to get procmail working with it you'll need to:

  1. Put a line containing just “DEFAULT=./Maildir/” at the top of your ~/.procmailrc file — that way procmail delivers to your Maildir folder instead of trying to deliver to /var/spool/mail/$USER.
  2. Put this in your ~/.qmail file:
| preline procmail

This will cause all your mail to be delivered via procmail instead of being delivered directly into your mail directory. ✨

See the qmail(7) documentation for more about mail delivery with qmail.

👑 postfix setup

If you use postfix(1), you can set up a system-wide mail filter by:

  1. Creating a user account for the purpose of filtering mail
  2. Populating that account's .qsfdb
  3. Creating a shell script, to run as that user, which runs qsf on stdin and passes stdout to sendmail(8)
⚠️ Doing this requires some knowledge of postfix configuration, and care needs to be taken to avoid mail loops. Like, genuinely. Be careful. 😭

One qsf user's full HOWTO is included in the docs/ directory with this package. Go read it. It's giving tutorial energy. 🌸

TECHNICAL DETAILS ✨🧠💅

okay bestie, when a message gets passed to qsf, the whole thing goes through a glow-up: any attachments get decoded, all HTML elements get removed, and then the message text gets broken up into "tokens" — and a "token" here is literally one single word or URL. Each token gets hashed with the MD5 algorithm (why? we'll get to that, bestie), and that hash is then used to look up each token in the qsf database. 💖

For full details of which parts of an email (headers, body, attachments, etc) are used to calculate the spam rating, see the “Tokenisation” sub-section below. 👑

Inside the database, each token has two numbers attached: the number of times that token has been seen in spam, and the number of times it has been seen in non-spam. Those two numbers, plus the total number of spam and non-spam messages seen, are then used to give a "spamminess" value for that particular token. That "spamminess" value ranges from "definitely not spammy" at one end, through "neutral" in the middle, up to "definitely spammy" at the other end. No cap.

Once a "spamminess" value has been calculated for all the tokens in the message, a summary calculation is made to give an overall "is this spam?" probability rating for the message. If the overall probability is 0.9 or above, the message is flagged as spam. 🚩

In addition to the probability test is the "allow-list". If enabled (with the -a option), the whole probability check is skipped if the sender of the message is listed in the allow-list, and the message is not marked as spam. 🫶

When training the database, a message is split up into tokens as described above, and then the numbers in the database for each token are simply added to: if you tell qsf that a message is spam, it adds one to the "number of times seen in spam" counter for each token, and if you tell it a message is not spam, it adds one to the "number of times seen in non-spam" counter for each token. If you specify a weight, with -w, then the number you specify is added instead of one. 💅

To stop the database growing uncontrollably, the database keeps track of when a token was last used. Under-used tokens are automatically removed from the database. (The old method was to "prune" every 500 updates). 🧹

Finally, the reason MD5 hashes were used is privacy. If the actual tokens from the messages, and the actual email addresses in the allow-list, were stored, you could not share a single qsf database between multiple users because bits of everyone's messages would be in the database — things like emailed passwords, keywords relating to personal gossip, and so on. So, a hash is stored instead. A hash is a "one-way" function; it is easy to turn a token into a hash but almost impossible to turn a hash back into the token that created it. This means that you end up with a database with no personal information in it. The MD5 hash was used because it has a reasonable balance of speed and security for this purpose. 🔐✨

Tokenisation 🧚✨

When a message is broken up into tokens, various parts of the message are treated in different ways. First, all header fields are discarded, except for the important ones: From, Return-Path, Sender, To, Reply-To, and Subject. 👑

Next, any MIME-encoded attachments are decoded. Any attachments whose MIME type starts with text/ (generally, HTML and text) are tokenised, after having any HTML tags stripped. Any non-textual attachments are replaced with their MD5 hash (such that two identical attachments will have the same hash), and that hash is then used as a token. 🦋

In addition to single-word tokens from textual message parts, qsf adds doubled-up tokens so that word pairs get added to the database. This makes the database a bit bigger (although the automatic pruning tends to take care of that) but makes matching more exact. 💖

Special filters 🕵️♀️💅

As well as using the textual content of email to detect spam, qsf also uses special filters which create "pseudo-tokens" based on various rules. This means that specific patterns, not just individual words, can be used to determine whether a message is spam or not. 🔍

For example, if a message contains lots of words with multiple consonants, like "ashjkbnxcsdjh", then each time a word like that is seen the special token .GIBBERISH-CONSONANTS. is added to the list of tokens found in the message. If it turns out that most messages with words that trigger this filter rule are spam, then other messages with gibberish consonant strings will be more likely to be flagged as spam. 💀

Currently the special filters are:

  • GTUBE — Flags any message containing the string XJS*C4JDBQADN1.NSBN3*2IDNEN*GTUBE-STANDARD-ANTI-UBE-TEST-EMAIL*C.34X as spam - useful for testing that your qsf installation is working. 🧪
  • ATTACH-SCR, ATTACH-PIF, ATTACH-EXE, ATTACH-VBS, ATTACH-VBA, ATTACH-LNK, ATTACH-COM, ATTACH-BAT — Adds a token for every attachment whose filename ends in .scr, .pif, .exe, .vbs, .vba, .lnk, .com, and .bat respectively (these are often viruses). 🦠
  • ATTACH-GIF, ATTACH-JPG, ATTACH-PNG — Adds a token for every attachment whose filename ends in .gif, .jpg or .jpeg, and .png respectively. 🖼️
  • ATTACH-DOC, ATTACH-XLS, ATTACH-PDF — Adds a token for every attachment whose filename ends in .doc, .xls, or .pdf respectively (these tend to indicate a non-spam email). 📄
  • SINGLE-IMAGE — Adds a token if the message contains exactly one attached image. 🌸
  • MULTIPLE-IMAGES — Adds a token if the message contains more than one attached image. 🌈
  • GIBBERISH-CONSONANTS — Adds a token for every word found that has multiple consonants in a row, as described above. Spam often contains strings of gibberish. 😵‍💫
  • GIBBERISH-VOWELS — Adds a token for every word found that has multiple vowels in a row, eg "aeaiaiaeeio". 🗣️
  • GIBBERISH-FROMCONS — Like GIBBERISH-CONSONANTS, but only for the “From:” and “Return-Path:” addresses on their own. 📬
  • GIBBERISH-FROMVOWL — Like GIBBERISH-VOWELS, but only for the “From:” and “Return-Path:” addresses on their own. 📮
  • GIBBERISH-BADSTART — Adds a token for every word that starts with a bad character such as %. 🚫
  • GIBBERISH-HYPHENS — Adds a token for every word with more than three hyphens or underscores in it. ➖
  • GIBBERISH-LONGWORDS — Adds a token for every word with over 30 characters in it (but less than 60). 📏
  • HTML-COMMENTS-IN-WORDS — Adds a token for every HTML comment found in the middle of a word. Spam often contains HTML inside words, like this: w<!--dsgfhsdgjgh-->ord 👀
  • HTML-EXTERNAL-IMG — Adds a token for every HTML <img> (image) tag found that contains :// (that is, it refers to an external image). 🌐
  • HTML-FONT — Adds a token for every HTML <font> tag found. 🔤
  • HTML-IP-IN-URLS — Adds a token for every URL found containing an IP address. 🖥️
  • HTML-INT-IN-URL — Adds a token for every URL found containing an integer in its hostname. 🔢
  • HTML-URLENCODED-URL — Adds a token for every URL found containing a % sign in its hostname. 🧩

Normally, filters will just cause a token to be added, and these tokens are processed by the normal weighting algorithm. However, the GTUBE filter will immediately flag any matching message as spam, bypassing the token matching. 🚨

Database backends 💾✨

The inbuilt "list" database backend does not provide the best possible performance, but is always available because using it requires no external libraries. 🎀

If, when qsf was compiled, the correct libraries were available, then it will be possible to use qsf with alternative database backends. To find out which backends you have available, run qsf -V (capital V). To see how well a backend performs, collect some spam and non-spam and use the benchmark tool: qsf -d BACKEND -B SPAM NONSPAM (refer to the description of the -B option). 📊

Some people find that they get the best performance out of the gdbm backend; this is a library that is widely available on many systems. 🌟

To efficiently use the same qsf database on multiple machines, you may find the MySQL backend useful. However, using it is a little more complicated. 🐬

To use the MySQL backend you will need to create a table with the fields key1, key2, token, value1, value2 and value3. The token, value1, value2, and value3 fields must be VARCHAR(64), BIGINT or INT, and BIGINT or INT respectively, and indexing on the token field is a good idea. The key1 and key2 fields can be anything, but they must be present. 💅

For example:

USE mydatabase;
CREATE TABLE qsfdb (
  key1      BIGINT UNSIGNED NOT NULL,
  key2      BIGINT UNSIGNED NOT NULL,
  token     VARCHAR(64) DEFAULT '' NOT NULL,
  value1    INT UNSIGNED NOT NULL,
  value2    INT UNSIGNED NOT NULL,
  value3    INT UNSIGNED NOT NULL,
  PRIMARY KEY (key1,key2,token),
  KEY (key1),
  KEY (key2),
  KEY (token)
);

The key1 and key2 fields allow you to have multiple qsf databases in one table, by specifying different key1 and key2 values on invocation. 🔑

Instead of specifying a database file with the --database/-d option, you must specify either a specification string as described below, or the name of a file containing such a string on its first line. 📁

The specification string is as follows:

database=DATABASE;host=HOST;port=PORT;
user=USER;pass=PASS;table=TABLE;
key1=KEY1;key2=KEY2

This string must be all on one line, with no spaces. 🚫

  • DATABASE — is the name of the MySQL database. 🗄️
  • HOST — is the hostname of the database server (eg "localhost"). 🏠
  • PORT — is the TCP port to connect on (eg 3306). 🔌
  • USER — is the username to connect with. 👤
  • PASS — is the password to connect with. 🔑
  • TABLE — is the database table to use. If a table with this name does not exist when qsf is called in update or training mode, then it will be created if permissions allow this to be done. 📋
  • KEY1 — is the value to use for the key1 field. 🔢
  • KEY2 — is the value to use for the key2 field. 🔢

Since command lines can be seen in the process list, it is advisable to specify a filename (such as qsf -d mysql:qsfdb.spec) and put the specification string inside that file. 🔒

REPORTING BUGS 🐛💖

Please report bugs or feature requests via the issue tracker linked from the qsf home page. 🫶

SEE ALSO 👀✨

procmail(1), procmailrc(5), procmailex(5) 🌈

Copyright © 2003-2007, 2015, 2021, 2025 Andrew Wood. 💖

License Artistic-2.0: Artistic License 2.0.

Okay so bestie, here's the legal tea, and it's actually the good kind 🫶 — this is free software: you are free to change it and redistribute it. Periodt. Do whatever, remix it, ship it, slay.

⚠️ But there is NO WARRANTY, to the extent permitted by law. Ngl that's just how it is — no cap, no promises, no takebacks. 💀

And if you wanna see literally everyone who helped make this happen, please see the package's ACKNOWLEDGEMENTS file for a complete list of contributors. The whole squad. The group chat. Every single icon 👑✨

Okay that's the whole page, bestie — you made it to the end 🦋 This one's qsf version 1.2.23, dated 2025-07-06, and honestly? Iconic. Go forth and query safely, main character 💅🌸💜

📦 where this page comes from