Some notes on the programs in this directory,

Domains, extension addresses, usernames: It is important to understand that
for mail to be delivered to a hashed mailbox, you'll need a mailbox with
the domain. It's likely, however, that your users will collect their mail
with POP3, and that their username won't include the domain (but note that
for some people, including the domain in the username may be a big plus).
If you want to setup a system where users have a simple name, you can
create their mailbox,

   addhashuser john

and then add all the E-mail addresses they may receive mail on,

   addhashalias sales@talltrees.com
   addhashalias john@gardens.com

For this user to pickup their mail, 'john' must be able to authenticate -
you need to setup authentication for 'john' separately - that's not covered
by this set of programs.

I haven't given much thought to how this hashing system affects extension
addresses - so if this is a functionality you require, you may find that
using this hashing system 'Breaks' extension addresses. Take care.

If you have one domain that requires 'extra-special' treatment, you could
still handle this outside the hashed system by having specific entries in
control/virtualdomains and users/assign. This could divert the mail to a
more conventional qmail setup.

qmail-local has been modified (qmail-local.patch) to turn incoming addresses
into lower case prior to hashing them to locate their directories. I haven't
changed the code for the DTLINE (Delivered-To: header) however to reflect
this change of case. This is because a system may have some users configured
to use hashing, while others don't - for the latter I don't want to break
anything.

Shared storage: These programs are built around the idea of the mailstore
being shared across multiple front-ends. Although this is not mandatory,
the programs are written with this in mind.

Admin programs: At present, these programs do not use any form of locking,
so that if separate instances of admin programs wish to manipulate a user's
directory, there may be a clash.

Disk, i-node usage: I decided that I wanted to keep track of aliases to
a hashed directory in an easy-to-implement way. The obvious approach is
to put a list of aliases in a file, but I chose to touch files in a
directory for this purpose instead. This may be regarded as wasteful of
resources (esp. i-nodes); the reason for doing it is that this reduces
problems of admin programs contending for an operation on a user's
directory. It also means some of the admin programs can be written
in shell script rather than coded in C - making them more understandable.

Scalability and hashes: The default hashes chosen are designed to allow
for a system built on this hashed structure to scale. Typically this
might go as follows:

    1. Single machine with local storage
    2. Single machine with remote storage device (e.g. NetApp)
    3. Multiple machines with remote storage device
    4. Multiple machines with multiple remote storage devices

The hashed directory structure is consistent across these 4 topologies:

    1. maildirs_basedir on local storage, hashed directories on local storage
    2. maildirs_basedir on local storage (mount point for remote storage),
       hashed directories on remote storage
    3. As 2.
    4. maildirs_basedir and first level hashes on local storage; these
       form the mount points for the remote storage. The remote storage
       devices each hold one or more hashed directory structures
       corresponding to the first level hashes.

As the code stands, a maximum of 19 remote storage devices are easily
accomodated. Adjust HASH1 if this is insufficient (but not once you've
deployed the hashing code, since the hashed directory locations alter
if you alter the hashes). See USAGE.NOTES, however, regarding [the hashing
version of] qmail-local making certain assumptions if it can find the 1st
level hash.