NAME

assassind - Spam filtering SMTP proxy that uses SpamAssassin

SYNOPSIS

assassind [--port=n] [--relayhost=hostname[:port]] [--user=username] [--group=groupname] [--maxrequests=n] [--dead-letters=/path] [--pid=filename] [--green=n] [--blue=n] [--yellow=n] [--red=n] [--maximum-check-size=n] [--[no]scan] [--infected-action=email|store|discard|header] [--infected-address=address] [--infected-directory=directory] [--infected-header=header]

assassind --help

DESCRIPTION

assassind is a relaying SMTP proxy that filters spam using SpamAssassin. The proxy is designed to be robust in the face of exceptional errors, and will (hopefully) never lose a message. In addition to scanning for spam, assassind can optionally scan for viruses using F-Prot.

assassind is meant to be used as a system-wide message processor, so the proxy does not make any changes to existing message contents or headers; instead choosing just to add four headers of its own, which end users can use to make decisions about filtering (or not filtering) their spam.

When acting as a virus scanner, assassind can be configured to simply add a special header to infected messages, discard the messages, store them somewhere in the filesystem, or forward them to a special mailbox.

The most important header that assassind adds is the X-Spam-Color header. This header will have one of five values: green, blue, yellow, orange and red. Green messages are very unlikely to be spam, while red messages are almost guaranteed to be spam. You can use this header as the basis for your own message filtering rules, using any common message filtering system (procmail, sieve, etc.).

In addition to the X-Spam-Color header, assassind adds a X-Spam-Score header, which contains the exact SpamAssassin spam score for the message.

assassind also adds a X-Spam-Status filter. This header is the same as the header generated by the standard SpamAssassin message processor, and contains the message's SpamAssassin score and other information.

Finally, assassind adds one or more X-Spam-Report headers, which contain a plain-text report of the rules that SpamAssassin used to assign the message its score.

assassind logs all aspects of its operation to syslog(8), using the mail syslog facility. Note: some versions of Net::Server have a bug with logging to syslog. This bug seems to affect at least version 0.85, and possibly others. Contact me for more information.

OPERATION

assassind is meant to operate as a mail relay that sits between the Internet and your internal mail system. The three most common configurations include

Running between firewall and internal mail server: The firewall would be configured to forward all of its mail to the port that assassind listens on, and assassind would relay its messages to port 25 of your internal server. assassind could either run on its own host (and listen on any port) or it could run on the mail server (and listen on any port except port 25). This is assassind default mode of operation.
Running on the firewall with an internal mail server: assassind would accept messages on port 25 and forward them to the mail server that is also listening on port 25. Note that assassind does not do anything other than check for spam, so it is not suitable as an anti-relay system. If your current mail system is configured correctly for anti-relaying, it should continue to work correctly in this configuration, but you may want to verify this using one of the standard open-relay blackhole testing systems.
Running on the mail server, which is not behind a firewall: In this configuration assassind would listen on port 25, while your mail server would be configured to listen on some other port.

OPTIONS

--port=n: Specifies what port assassind listens on. By default, it listens on port 2025.
--relayhost=hostname[:port]: Specifies the hostname where assassind will relay all messages. Defaults to localhost. If the port is not provided, that defaults to 25.
--user=username =item --group=groupname: Specifies the user and group that the proxy will run as. Default is mail/mail.
--maxrequests=n: assassind works by forking child servers to handle each message. The maxrequests parameter specifies how many requests will be handled before the child exits. Since a child never gives back memory, a large message can cause it to become quite bloated; the only way to reclaim the memory is for the child to exit. The default is 20.
--dead-letters=/path: Specifies the directory where assassind will store any message that it fails to deliver. The default is /var/tmp. You should periodically examine this directory to see if there are any messages that couldn't be delivered.; Important! This path should not be on the same partition as your mail server's message spool, because if your mail server rejects a message because of a full disk, assassind will not be able to save the message, and it will be lost.
--pid=filename: Specifies a filename where assassind will write its process ID so that it is easy to kill it later. The directory that will contain this file must be writable by the assassind user. The default is /var/run/assassind/assassind.pid.
--green=n =item --blue=n =item --yellow=n =item --orange=n: Specifies the spam score thresholds for each color. The defaults are 5, 6, 10 and 20. Anything over 20 will have a color of red.
--maximum-check-size=n: Specifies the maximum size of messages that will be checked via SpamAssassin. Any message over this size will be passed through as non-spam without scanning, which can improve performance significantly. The number can be appended with K or M to represent kilobytes or megabytes, respectively (e.g., --maximum-check-size=3k). The default is 10K. Most spam messages have a fairly small payload, so anything over 10K is not likely to be spam.; Note that every message is scanned for viruses, regardless of its size.
--scan: Enable virus scanning of each message.
--infected-action=action: Specify the action to take if a message is infected with a virus. Valid actions are header (the default), email, store and discard.; The header action will add an extra email header to the message before relaying. The name of the header is specified with the --infected-header option. The value of the header is always Yes.; The email action relays the email to an alternate mailbox rather than relaying the message to the original recipient(s). The --infected-email option specifies the mailbox to use.; The store action stores the email in a file in the filesystem. The --infected-directory specifies the directory where the file will be stored.; The discard action discards the email.
--infected-header=header: The name of the header to add to an infected email. Defaults to X-Has-Virus.
--infected-email=email: The address to relay infected emails to. This option is mandatory if the --infected-action action is email.
--infected-directory=directory: The directory to store infected email in. This option is mandatory if the --infected-action action is store. For maximum performance, the directory should be on the same filesystem as the dead letters directory.

EXAMPLES

Running between firewall and internal mail server

This is assassind's default configuration, where it listens on port 2025 on the same host as the mail server.

  assassind

Running on the firewall with an internal mail server

  assassind --port=25 --relayhost=internal.serv.er

Running on the mail server, which is not behind a firewall

This scenario assumes that the real mail server is running on port 2025 of the same host.

  assassind --port=25 --relayhost=localhost:2025

AUTHOR

Dave Carrigan, <dave@rudedog.org>

This program is distributed ``as is'', without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The entire risk as to the quality and performance of the program is with you. Should the program prove defective, you assume the cost of all necessary servicing, repair or correction.

BUGS

Due to the nature of Perl's SMTP::Server module, a SMTP message is stored completely in memory. However, as soon as the module receives its entire message data from the SMTP client, it returns a 250, signifying to the client that the message has been delivered. However, this means that there is a period of time where the message is vulnerable to being lost if the assassind process is killed before it has relayed or saved the message. Caveat Emptor!