OVERVIEW

This directory contains the source code for filtercmd, a setuid binary that
serversidefilter uses in order to read and write filter/forward files. 

COMPILING AND INSTALLING

To compile filtercmd, edit the Makefile to change any settings, and then run
make. Then run make test to ensure the setuid binary / configuration
settings are set up properly. The binary should reside in this directory.

PREREQUISITES

* A C compiler
* Root access. This script must be setuid root, because it will need to
  write files as any mail user on the system.
* The c-client library. The Makefile has more details.

TROUBLESHOOTING

* When I visit the options page, I get a strange error at the top of the
page and my filters are not saved.

Read the number at the end of that error message and find the explanation
below.

* I am getting error 4, "filtercmd - setgid: Operation not permitted"

The binary is not setuid root. Run this command, "sudo chmod 4750 filtercmd".

* I am getting error 126

You didn't change the group in the makefile. Run this command, 
"sudo chgrp apache filtercmd", replacing apache with your web server's group.

* I am getting error 10, "Can't read imap server from configfile"

filtercmd expects to find the squirrelmail configuration file in a certain place
(specified in the Makefile). Did the squirrelmail/config.php file move?

* I am getting error 12, "Bad credentials"

This means the IMAP connection is not working. Compile the filtercmd with
debugging on and run test.sh to find out why. This can sometimes be fixed by 
adding options such as /notls to the MAILBOXNAME setting in the Makefile.

* I am getting error 13, "Can't verify credentials, IMAP not supported by library"

This error message means that the c-client library was mis-compiled -- you
will have to either compile the c-client library by hand or find a working
version.

* I am getting error 14, "Can't look up virtual user"

Check that the domain (everything after the @ in the username) was not found in the "virtualdomains"
file. 

* I am getting error 15, "Can't trust config file -- make sure they are all owned by root"

filtercmd requires that the configuration files it consults are all
root-owned. This ensures that the decisions filtercmd makes about which
files to write are not based on tampered configuration files. All of the
parent directories are checked as well. So, check the ownership of the
configuration files, and the parent directories of those configuration
files:

   /etc/squirrelmail/config.php
   /usr/share/squirrelmail/plugins/serversidefilter/config.php
   /usr/share/squirrelmail/plugins/serversidefilter/virtualdomains

* I don't have root access.

filtercmd can work in "single user" mode. Change the permissions of the file
to 6755 and make sure it is owned by the user and group that owns the
filter/forward files. Other users accessing the filtering page will get
error 4. Note that the restrictions outlined while explaining error 15 still
apply -- so without root access you still may not be able to run
serversidefilter.

