              Mailfilter Frequently Asked Questions and Answers

  ------------------------------------------------------------------------

General Questions:

   * What is Mailfilter?
   * Who needs Mailfilter?
   * How does Mailfilter interact with my current e-mail environment?
   * Where do I find out more about Mailfilter?
   * I think, I found a bug in Mailfilter. Will you fix it?
   * I have good ideas for new features. Will you implement them?

Installation:

   * What are the system's requirements to install and run Mailfilter?
   * What should I know to make Mailfilter run on Windows 9x/2000/NT?
   * How do I install Mailfilter?
   * Running 'configure' doesn't work.
   * Running 'make' doesn't work.
   * Running 'make' was easy, but running 'make install' doesn't work.
   * Is there any way to decrease the size of the mailfilter binary?

Configuration:

   * Mailfilter complains that its rcfile (~/.mailfilterrc) is missing.
   * Mailfilter complains that its logfile can't be accessed.
   * Mailfilter complains about the syntax of my rcfile.
   * How do these filters work? What are Regular Expressions anyway?
   * Can I override some filters? (How to define 'friends' lists)
   * How do I fine tune other programs to work with Mailfilter?
   * Are there any sample rcfiles (~/.mailfilterrc) ?

Run-time Errors:

   * Because of some missing libraries, Mailfilter won't start.
   * Mailfilter complains that a specific file couldn't be accessed.
   * I get DNS lookup errors.
   * Mailfilter says it sent a specific command to the server, but it
     responded with an error.
   * Mailfilter says that some keyword is deprecated.
   * The compilation of Regular Expressions failed.

Special Features:

   * Can Mailfilter check more than one account?
   * Does Mailfilter support any other protocols besides POP3?
   * Is there a way to send encrypted password information to the server?
   * How can I get Mailfilter to auto-reply to spam?

Miscellaneous:

   * I think I accidently deleted an important e-mail with Mailfilter. Can I
     get it back somehow?
   * If I make changes to rcfile, does it affect immediately?
   * Sometimes a few (spam-) messages slip through. How come?
   * My question is not covered by this FAQ. Help!!

  ------------------------------------------------------------------------

General Questions:

   * What is Mailfilter?

     Mailfilter is a flexible utility for UNIX (-like) operating systems to
     get rid of unwanted spam mails, before having to go through the trouble
     of downloading them into the local computer. It offers support for one
     or many POP3 accounts and is especially useful for dialup connections
     via modem, ISDN, etc.
     Mailfilter connects to any POP3 mail box and compares part of its
     content to a set of user defined filter rules. That way the spam gets
     deleted directly on the mail server.
     With Mailfilter you can define your own filters (rules) to determine
     which e-mails should be delivered and which are considered waste. Rules
     are Regular Expressions, so you can make use of familiar options from
     other mail delivery programs such as e.g. procmail.
     Mailfilter is released under the terms of the GNU General Public
     License. For more information, see the README and COPYING documents
     provided with the Mailfilter program.

   * Who needs Mailfilter?

     If you do not pick up your e-mail from a POP3 server, then there is no
     need to install Mailfilter. But if you do get your e-mail from one or
     many POP3 accounts and if you are sick and tired of downloading
     megabytes of worthless spam (usually those are anonymous
     advertisements, chain mails, etc.), then you should give Mailfilter a
     try.
     It will help save you band width and time by deleting spam directly on
     your server, before you have to download and read those messages. By
     defining your own personal filter rules, you can tell Mailfilter which
     e-mails should be deleted.

   * How does Mailfilter interact with my current e-mail environment?

     It doesn't matter which programs you use to fetch your mail with,
     because Mailfilter is an independent application. It will not interfere
     with your favourite e-mail client. You may just want to start
     Mailfilter everytime you are about to download new e-mail from a POP3
     server, or maybe just once a day. That's entirely up to you.
     However, if you are using highly configurable mail programs such as
     fetchmail, then there are some clever ways to get Mailfilter cooperate
     with them directly. Section "How do I fine tune other programs to work
     with Mailfilter?" describes this in more detail.

   * Where do I find out more about Mailfilter?

     All relevant documentation for Mailfilter (including this FAQ) is
     provided with the Mailfilter distribution. Online versions of some of
     these documents are available on the official Mailfilter homepage:

     http://mailfilter.sourceforge.net/

     On this homepage you may also find additional information on Regular
     Expressions and related links to other programs that work well with
     Mailfilter. If you have already installed the program, be sure to read
     the man pages mailfilter(1), mailfilterrc(5) and mailfilterex(5).

   * I think, I found a bug in Mailfilter. Will you fix it?

     If it really is a bug you found (not a feature), then I will of course
     try to do something about it. Generally it's a good idea to report bugs
     to the mailing list mailfilter-dev@lists.sourceforge.net, but you can
     also directly contact the author of Mailfilter. When you report bugs,
     please provide as much additional information as possible on what may
     have caused the problems and what consequences you suffered. Such
     information always includes the name of your operating system and
     hardware platform, description of your network connection and excerpts
     from the Mailfilter log files. When creating a log file, please use the
     highest level of verbosity available.

     mailfilter --verbose=6

     And don't forget to remove your usernames and passwords from the logs
     before posting them to the Mailfilter mailing list!!

   * I have good ideas for new features. Will you implement them?

     Of course that depends on the feature you are asking for. There are
     some frequently requested features ('autoreply' ranks very high) that
     will most likely never make it into the source code, but at this point
     I am sure Mailfilter could be expanded with dozens of useful additions
     and I'm glad to hear them (if they are not too far 'off the track').
     I'm even more glad if you're able to help implement them.

  ------------------------------------------------------------------------

Installation:

   * What are the system's requirements to install and run Mailfilter?

     Here is an excerpt from the INSTALL file that is part of the source
     archive of Mailfilter:

     To run Mailfilter it's best to have a UNIX (-like) operating system,
     but it also compiles fine with Windows 9x/NT/2000 if additional libraries
     and tools are installed (e.g. Cygwin or DJGPP). So far Mailfilter has
     been successfully compiled and tested with

      - Solaris 8 / SunOS 5.8

      - Irix 6.5

      - FreeBSD 4.1.1-RELEASE

      - NetBSD 1.5

      - Linux:  Mandrake 7.0 - 7.2, Debian 2.1, RedHat 6.2 - 7.0,
                Slackware 3.9 (See README.Slackware for further details)
                SuSE 6.2, LinuxPPC

      - Windows NT (See README.Windows for further details)

     but it may well work on other platforms, too. (Please report success if
     you have managed to compile it on any other system - thanks.)

     To install Mailfilter you also need to have a fairly recent version of
     the GNU C++ compiler (e.g. 2.95.x) and your system must support BSD-type
     sockets (in general all UNIX systems do meet this criterion). Since
     version 0.0.2 of Mailfilter you also need to have a standard C compiler
     to translate some additional libraries.

   * What should I know to make Mailfilter run on Windows 9x/2000/NT?

     Mailfilter was originally designed to only support UNIX (-like)
     operating systems. But if you have additional libraries such as the
     Cygwin environment, DJGPP or MinGW installed, then you should also be
     able to translate the program on your Windows 9x/2000/NT platform. Have
     a look at the README.Windows file that comes with the Mailfilter
     distribution or consult the homepage for additional information and
     pre-compiled binaries.

   * How do I install Mailfilter?

     If you have downloaded the compressed Mailfilter source code archive,
     then please refer to the INSTALL file provided by that archive. Binary
     packages (if available for a particular program version) should be
     installed as any other package of that kind. For example you could use
     the command 'rpm -U packagename.rpm' for RedHat packages.
     Note: even if you did not encounter any problems installing the
     program, I strongly recommend reading the INSTALL file anyway in order
     to find out about the set-up of Mailfilter. The program does not work
     without spending a little bit of time on configuration first.

   * Running 'configure' doesn't work.

     If your system lacks some of the requested
     features/libraries/compilers, then try installing them and run
     'configure' again. But don't forget to remove the file config.cache
     first, or the new components can not be found. If it's a more serious
     problem that can't be fixed that way, consider reporting it as bug.

   * Running 'make' doesn't work.

     The most common reason why 'make' fails is that your system does not
     offer a recent version of the GNU C++ compiler (gcc) or its libraries.
     Releases prior 2.95.x don't know C++ namespaces and therefore choke on
     Mailfilter's source code. Updating your compiler should fix these sorts
     of problems. Also note that Mailfilter needs a standard C compiler to
     translate additional C source code.

   * Running 'make' was easy, but running 'make install' doesn't work.

     The most common cause for this behaviour is that you are trying to
     install Mailfilter into a directory where you do not have the necessary
     permissions to write in. Either reconfigure your Makefile with these
     options

     make clean
     ./configure --prefix=/newdir

     where 'newdir' points to the new location for Mailfilter, or simply
     become root and then run 'make install' again. By default this will
     install the software in /usr/local/bin.

   * Is there any way to decrease the size of the Mailfilter binary?

     For users of UNIX-like systems, yes. When installing the program,
     running 'make install-strip' instead of 'make install' will strip the
     binary as it installs it, drastically decreasing its size.
     If you've already installed mailfilter, but still wish to strip the
     binary, become root, and use the strip command. See the manual page of
     strip(1) for more information.

  ------------------------------------------------------------------------

Configuration:

   * Mailfilter complains that its rcfile (~/.mailfilterrc) is missing.

     Read the INSTALL file provided with Mailfilter, in which you will find
     an example rcfile set-up. Copy and paste this example, modify it to
     suit your own needs and restart Mailfilter. (Alternatively you can also
     look up the official homepage to find a basic set-up that gets you
     started.) If the program still complains, then try to start it with the
     '--mailfilterrc' switch, pointing directly to the new location of your
     rcfile.
     Note: you must have a rcfile file installed somewhere.

   * Mailfilter complains that its logfile can't be accessed.

     Every rcfile must set the LOGFILE option. Check the given path of your
     logfile in the rcfile, or simply start Mailfilter with the '--logfile'
     switch pointing directly to the desired location. If that doesn't help,
     then check the permissions of the directory where you want Mailfilter
     to store its logs in. It has to be writeable.

   * Mailfilter complains about the syntax of my rcfile.

     Not to worry, you probably misspelled a word or two in the rcfile, or
     you have a couple of 'spaces' hidden somewhere. Read through it
     carefully and keep in mind that the commands are case sensitive.
     Therefore it does matter whether you say 'DENY' or 'Deny' (which would
     cause a program failure). Typically an entry in ~/.mailfilterrc looks
     like this

     SERVER=myserver.domain.com

     Commands must be written in capitals, followed by a '=' and there are
     no spaces in between or after. Each command has to be in a separate
     line.

   * How do these filters work? What are Regular Expressions anyway?

     With Mailfilter you can define your own filter rules to determine which
     e-mails are considered waste and what should be downloaded into your
     local computer. Such rules are defined by using Regular Expressions. It
     is very common for these kinds of programs to employ this technique
     because of its great flexibility. Consider this simple example: if you
     are not interested to get the 200th advertisement containing
     information about Viagra, you might want to add this to the end of your
     rcfile

     DENY=^Subject:.*Viagra

     Now every e-mail that contains anything about Viagra in the subject
     line gets deleted instantly. You can create similar rules for all of
     the other header fields (cc, To, From, etc.), but be aware of the fact
     that Mailfilter does not allow more than one line per rule. So each new
     filter must be placed in its own line starting with 'DENY='. If you
     don't want the filter rules to be case-sensitive then you also have to
     add this line to your rcfile:

     REG_CASE=no

     A comprehensive list of all supported keywords can be found in the
     mailfilterrc(5) man page. More examples and real-life use cases can be
     looked up in the mailfilterex(5) man page. Study these documents
     carefully! If you're eager to know how Regular Expressions work in
     general, use your favourite UNIX book or have a look at the official
     Mailfilter homepage. There you will find some enlightening links on
     this subject.

   * Can I override some filters? (How to define 'friends' lists)

     Yes, using the keyword ALLOW you can define which messages should be
     delivered, regardless of any spam filters that might match. This way
     you can not only define 'friends' lists, but also create a very
     restrictive rule set. Consider this example:

     DENY=^From:.*@spam_isp.org
     ALLOW=^From:.*my_friend@spam_isp.org

     Adding these two lines to your rcfile will filter all messages coming
     from the domain 'spam_isp.org', except for those from your friend
     'my_friend' (who should obviously change his ISP). A comprehensive list
     of all supported keywords can be found in the mailfilterrc(5) and
     mailfilterex(5) man pages. Study them carefully!

   * How do I fine tune other programs to work with Mailfilter?

     As always, there are various ways to achieve this. I have chosen the
     commonly used application fetchmail to explain how this works.
     Fetchmail is a nifty program that downloads e-mail from POP3 accounts
     (it also supports other protocols). Therefore it's a very tempting idea
     to use the clean up services of Mailfilter before we're starting to
     receive huge amounts of junk in between our normal e-mail messages.
     Adding one single line to the fetchmail set-up file does the trick:

     poll my.mailserver.de via "my.mailserver.de"
      with proto POP3
         localdomains mailserver.de
            user "username" there with password "pass" is tuxuser here
            options forcecr warnings 3600
            preconnect "mailfilter"

     poll my2.mailserver.de via "my2.mailserver.de"
      with proto POP3
         localdomains mailserver.de
            user "anotherusername" there with password "other_pass" is tuxuser
            here options forcecr warnings 3600

     The line 'preconnect "mailfilter"' tells fetchmail to invoke Mailfilter
     each time the user requests the download of new e-mail messages. If
     Mailfilter is set up to check both of the given accounts then calling
     it merely once is sufficient.
     Another very good (and popular) way of using Mailfilter is to call it
     via cron, or just once upon login. That way you won't see much of it
     either and can work with your favourite e-mail program just as you are
     used to - except you won't be disturbed by spam anymore.

   * Are there any sample rcfiles (~/.mailfilterrc) ?

     Yes, there are. You can find one in the INSTALL file provided with
     Mailfilter, or check whether the official web page provides further
     examples (a section which will certainly be expanded in the future). A
     comprehensive list of all supported keywords can be found in the
     mailfilterrc(5) and mailfilterex(5) man pages. Study them carefully!

  ------------------------------------------------------------------------

Run-time Errors:

   * Because of some missing libraries, Mailfilter won't start.

     So far I have only witnessed this behaviour on Solaris. If you get an
     error message similar to this

     ld.so.1: ./mailfilter: fatal: libstdc++.so.2.10.0: open failed: No such
     file or directory

     then your library path is not set properly. To fix the problem, simply
     type something like this in your shell (if it's bash - otherwise you
     may have to use 'set' instead of 'export') depending on the path of
     your libraries (sometimes they're also in /opt/lib)

     export LD_LIBRARY_PATH=/usr/lib:/usr/local/lib:$LD_LIBRARY_PATH

   * Mailfilter complains that a specific file couldn't be accessed.

     Most likely you need to fix up your Mailfilter configuration. Please
     refer to the "Configuration" section in this FAQ.

   * I get DNS lookup errors.

     Such errors occur when the Domain Name Server failed to resolve the
     name of your POP3 server. This either happens when you have misspelled
     the server name in your rcfile, or when you are trying to start
     Mailfilter even though you have not established a network connection
     first.

   * Mailfilter says it sent a specific command to the server, but it
     responded with an error.

     Usually these errors occur when you are trying to get your mail from a
     server that does not fully support the POP3 transfer protocol. But you
     can also get this behaviour if your network connection (or only the
     connection to the POP3 server) drops during a mail box examination. In
     this case, simply try to envoke Mailfilter again. If that doesn't fix
     it, consider reporting a bug.

   * Mailfilter says that some keyword is deprecated.

     This may happen occasionally when updating from an old version of
     Mailfilter to a new one. Usually the program suggests a new keyword in
     its error message though. But you can also look up the proper defintion
     in the documentation files that come with the Mailfilter distribution,
     or consult the mailfilterrc(5) man page. It contains a comprehensive
     list of all supported and deprecated keywords.

   * The compilation of Regular Expressions failed.

     Extended Regular Expressions are not 100% compatible to the basic kind
     of expressions. Check if you have set Mailfilter to support extended
     expressions (keyword REG_TYPE) and adjust your filters if necessary.
     Another reason could be the Cygwin environment, if you encounter this
     error on a Microsoft Windows platform. We are working on it, but please
     submit a bug report anyway, so we can get as much information about
     this problem as possible. Thank you.

  ------------------------------------------------------------------------

Special Features:

   * Can Mailfilter check more than one account?

     Of course it can. Personally, I despise all e-mail programs that have
     such stupid limitations. How many users nowadays have only one account
     anyway?

   * Does Mailfilter support any other procotols besides POP3?

     Not in the current version, but support for the IMAP protocol is
     planned.

   * Is there a way to send encrypted password information to the server?

     Not in the current version. This is another feature that I will look
     into though.

   * How can I get Mailfilter to auto-reply to spam?

     You can't and this is a feature that will never be implemented either.
     I started the Mailfilter project to prevent e-mail abuse in general not
     to give people a weapon to fight fire with fire. Apart from that it
     would be considered a criminal offense in most countries (including the
     one I'm living in) to answer a mail bomb with your own mail bomb.

  ------------------------------------------------------------------------

Miscellaneous:

   * I think I accidently deleted an important e-mail with Mailfilter. Can I
     get it back somehow?

     Tough. Once Mailfilter deleted an e-mail, all you get to see of it is
     where it came from, what it was about and when it was sent. Have a look
     in your logfile and ask the author to send it again. If that's not an
     option for you, you may want to ask your ISP to recover this message
     for you, though I doubt this would be a very successful undertaking.

   * If I make changes to the rcfile, does it affect immediately?

     If you are changing Mailfilter's settings while it's active, nothing
     special will happen. All changes you make in the rcfile will be
     considered next time you run the application.

   * Sometimes a few (spam-) messages slip through. How come?

     This is not a bug in Mailfilter. Consider it as a feature of every POP3
     e-mail server. Once you start checking for spam or downloading
     messages, the server locks the mail box. If new messages arrive during
     the locked state, they will be queued and provided for further
     processing after the lock has been removed.
     So Mailfilter does not see incoming messages while it checks for spam
     and sometimes it happens that a message or two arrive just in time to
     be too late for filtering, but in time for download. That's life.

   * My question is not covered by this FAQ. Help!!

     This FAQ can never be a 100% complete guide, covering all possible
     aspects of the Mailfilter program. If you do have an urgent question
     that you can't find answers for, feel free to contact me, the author of
     Mailfilter. Maybe the question will make it into the list of FAQs.
