vmail-sql for Exim
$Id: README,v 1.18 2002/07/03 10:44:11 chris Exp $
Chris Lightfoot http://www.ex-parrot.com/~chris/
Paul Warren http://www.ex-parrot.com/~pdw/
This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at your
option) any later version.
This is a set of Exim configuration sections and control scripts to allow
complete configuration of a virtual-domains email system using a MySQL
database; it includes a (now obsolete) patch to gnu-pop3d to allow you to use
that POP3 server with the virtual-domains set up, but we recommend that you use
tpop3d instead. See below.
Installation and upgrade instructions can be found in the INSTALL and
UPGRADE files respectively, but you should read this file for
information on how the configuration works.
The whole setup is not totally trivial, but here are the basics:
0. What You Need
Software--
* tpop3d, from http://www.ex-parrot.com/~chris/tpop3d/ (or, but not
recommended, gnu-pop3d, in a version to which the supplied patch will
cleanly apply; 0.9.8 has been tested)
* MySQL, or, more precisely, libmysqlclient (C client API)
* the exim MTA, in a version which supports MySQL natively (or, if you
wish to roll-your-own config, any MTA which can route by calling an
external program)
* perl 5, DBI and DBD::mysql, if you want to use the supplied scripts to
configure virtual domains
* Apache, or some other web server if you want to use the supplied CGI scripts
for configuring domains.
Hardware--
* a computer capable of running the above (with a connection to the
internet, if you have ambitions beyond talking to yourself)
Other--
* a clue or two; this is not a trivial setup and you will probably have
to work out (at least) infelicities in its configuration.
1. The Database
This has tables for domains, forwarders, and `POP3 boxes' (mail spools; the
terminology is lifted from a service this was designed to replace). There is
also a session table to support the web interface, but this is separate and may
be omitted if you don't want to use that. The schema, in MySQL syntax, is as
follows:
--- file init-db.sql ---
# this is the table which holds information about this domain
create table domain (
domain_name varchar(255) primary key, # domain name
unix_user varchar(255), # which Unix user owns files etc.
password_hash varchar(255), # admin password for this domain
path varchar(255), # base path for this domain
max_popbox int # maximum number of popboxes in this domain
) ;
# forwarders, local and remote
create table forwarder (
domain_name varchar(255) not null, # domain this refers to
local_part varchar(255) not null, # local part we forward for
remote_name varchar(255) not null, # whom we forward to
primary key (domain_name(16), local_part(32))
) ;
# local POP boxes (virtual)
create table popbox (
domain_name varchar(255) not null, # domain this refers to
local_part varchar(255) not null, # username for this POP box
password_hash varchar(255), # hash of this user's password
mbox_name varchar(255), # appended to domain.path
primary key (domain_name(16), local_part(32))
) ;
# domain aliases
create table domain_alias (
domain_name varchar(255) not null, # domain to redirect to
alias varchar(255) not null, # alias for 'real' domain
primary key (alias)
);
--- file init-session-db.sql ---
create table web_session (
domain_name varchar(255) primary key, # domain name
session_id char(32), # session token for this domain
expires int
) ;
This database is called `virtualemail' in our setup.
There is a MySQL user who has access to INSERT/SELECT/UPDATE/DELETE; in our
setup, this is `exim' but `vmail' might be a more logical choice.
The unix_user field in domain is essentially there to allow virtual domain
mailspools to be subject to quotas. It is not necessary to have a different
user for each domain.
2. The Exim Configuration
In sketch form:
Firstly, you need to tell Exim that the domains listed in the domain table of
the database are `local'. You probably have other local domains which you list
explicitly, so you should do something like
local_domains =