SYSTEM DEFAULTS
---------------

The file spam contained in the main magic config directory contains the
global rules which are loaded if a user's config file contains a rule
specifying to use global rules.

	/etc/magic/magicspam
	/etc/magic/magicspam.global

SYSTEM USERS
------------

User's will be searched for by first checking the qmail users/cdb file,
which is built using users/assign. If the user is not found in the cdb
database, the password file is then checked. If either of these checks is
successful, the user's home directory will be known, and will be called
~user. If the user isn't found the cdb or passwd file, the user is not
considered a system user.

Global rules for user@localdomain:

	~user/.magicspam

Rules that would match all user-ext@localdomain addresses:

	~user/.magicspam-default

Spam rules for a specific user-ext@localdomain address which will be
used over any -default files that may be found that would also match:

	~user/.magicspam-ext

With this scheme you can have spam filtering based on each individual
address or globally on all addresses which are sent to the user, whether
they match a .qmail-ext file or not.  But, if the .qmail-ext file is not
present for a given address, system will consider the user non-existent
(unless caught by a .qmail-default file) and the smtp daemon will return a
user does not exist message when an attempt to deliver mail is requested.

VIRTUAL DOMAINS
---------------

The following scheme does not add any extensions for virtual domains
and simply treats them as a system user.  This simplifies the code
and makes the system far more consistent.  If the rules are stored in
/etc/magic/spam, they must be owned by root, which means that either the
system administrator must update them manually, or there must be a SUID
program to update them.  This allows who ever owns the vpop directory to
change the spam rules for a given domain, or at least have system users
only running a program which is SUID and owned by vpop as opposed to root.

The virtualdomains file will contain the following lines:

	<vdomain>:<vdomain-user>

Which would then have in the users/assign file:

	<vdomain-user>:.*:~vdomain

The virtual domain prefix can also be included in th passwd file as a
regular user if desired and the following examples would have the same
effect if the home directory for the user is the same as that given in
the users/assign file.

Global rules for all mail delivered to a virtual domain "vdomain"

	~vdomain/.magicspam-default

Rules for an individual address user@vdomain

	~vdomain/.magicspam-user

Rules for an extension address user-ext@vdomain:

	~vdomain/.magicspam-user-ext

or a user-ext@vdomain catchall:

	~vdomain/.magicspam-user-default

and so on...

If a .magicspam file (no extension) would only apply to mail sent to
vdomain@localdomain and not to any mail actually sent to vdomain, so it
is not generally needed, although can be added if desired.

So basically, virtual domains are handled no differently than regular
system users if the virtualdomains and users/assign (and cdb) file are
setup correctly.  If not, something else has to be done.

An example would be:

virtualdomains:
wizard.ca:wizard.ca

users/assign
wizard.ca:.*:/home/vpopmail/domains/wizard.ca

A filter file for all mail to wizard.ca:
/home/vpopmail/domains/wizard.ca/.magicspam-default

A filter file for help@wizard.ca:
/home/vpopmail/domains/wizard.ca/.magicspam-help

Files required to check for existence of someone@wizard.ca:
either 
	/home/vpopmail/domains/wizard.ca/.qmail-someone
or
	/home/vpopmail/domains/wizard.ca/.qmail-default

If the .qmail-default is present, all users at a given domain are
considered valid.  To get around this, the administrator can provide
an external program which can be called to verify individual users.

There is (will be) another document in this directory which outlines
this program, the arguments passed and expected return codes.  If it's
not specified, all users at the domain are considered valid, so if spam
checking is desired, a .magicspam-default file will have to be present
for the system to have any effect.

ALIASES
-------

Aliases are handled just the same as regular system users, but with
their rules in the ~alias domain (which is found in the users/cdb file
if present or the passwd file if not) ie:

~alias/.magicspam-alias

Normal qmail installations will either have alias listed in the users/cdb
file or in the /etc/passwd file.  If not, we can't handle it and a user
does not exist message will be returned.

OLD STUFF (not relevant anymore)
---------

Virtual domain addresses are user@vdomain. vdomain
must be listed in the control/virtualdomains file,
and the prepend listed in that file must map to a
system user.

Although a virtual domain will map to a system user, most systems will
have them map to a single user (ie. vpopmail).  This is not acceptable,
as we cannot have a single set of spam rules for all virtual domains
handled by that user.  The solution is to have each domain contained in
a directory, with global rules for that domain, with individual users
for the domain in a directory contained within.

Virtual Domain global rules:
	/etc/magic/spam/vdomain/spam

Virtual domain individual user address rules:
	/etc/magic/spam/vdomain/user/spam

Alias user spam rules:
	/etc/magic/spam/alias/user

This looks like the only case that we can have here.  If all mail to
virtual domains was sent to vpop, the actual virtual domain part of the
message will be lost (user@wizard.ca and user@virtual.com would both be
sent to vpop-user).  This might be how systems do it, and then have the
back end delivery program sort it all out; in that case more thought
must be put into this.

The following describes two cases of handling virtual domains as found
in the qmail-users file.  All mail is sent to a single user (vpop) for
all mail to all virtual domains.  The first case has the home directory
of all virtual domains the same as vpop and the second specifies the
individual home directories for each virtual domain.

In users/assign file:
	( For all domains )
	vpop:.*:/home/vpop

	Which would lead to the following file structures:
	/home/vpop/.qmail-default
	/home/vpop/.qmail-domain-default
	/home/vpop/.qmail-domain-user

	Global rules for all mail delivered to vpop.
	/home/vpop/.magicspam-default

	Global rules for all mail delivered to a virtual domain "domain"
	/home/vpop/.magicspam-domain-default

	Rules for an individual address user@domain
	/home/vpop/.magicspam-domain-user
