>>> TMDA 
  
TMDA Homepage
[ AU | US mirror ]
TMDA @ SourceForge      
Overview
Introduction
History
Features
Results & Testimonials
TMDA In Use
Press Coverage
 
Install
Requirements
Download
Installation
 
Configuration
Overview
Pre-Configuration
Server Configuration
Client Configuration
Configuration Variables
Filter Specification
Filter Sources
 
HOWTOs
Overview
Templates
tmda-ofmipd
Virtual Domains
tmda-cgi
 
Support
Troubleshooting
FAQ
Bugs & Patches
Mailing Lists
List Archive
Commercial Support
External Resources
Mirrors
 
Author
Jason R. Mastaler
 
© 2001-2003
  

tmda-ofmipd + VPopMail or VMailMgr


In this HOWTO I will assume you are comfortable with basic UNIX skills and understand things like UIDs, home directories and so forth. If you are not, you should get a good UNIX tutorial/reference and learn about the basics. You should definitely not try to administer something as complicated as a mail server, particularly one serving multiple domains, until you are on speaking terms with UNIX.

Virtual Domains Background

Virtual domains are a neat feature of qmail where a single UID (/etc/passwd user) can control all the email addresses within a given domain. VPopMail and VMailMgr are add-ons to qmail's virtual domain system that provide POP/IMAP authentication and user/password management.

In the simple case, the name of the domain, say example.org, is placed in qmail's 'virtualdomains' file followed by a colon (:) and the name of the system user who controls the domain. Let's say that that user is 'example'. Just to clarify, I mean that there is an entry for the 'example' user in /etc/passwd and 'example' has a home directory, say '/home/example'.

All email coming in to <anything>@example.org will be forwarded to example-<anything>@example.org and delivered according to the rules found in /home/example/.qmail-<anything> or /home/example/.qmail-default.

A common situation on the Internet today is that people don't read mail from shell accounts. Instead, they are often running Windows machines and retrieve their mail via POP or IMAP. Thus the concept of a mailhub, where mail is delivered to a POP or IMAP mailbox but the individual users never log in to a shell.

Going back to our example, if we have the email users biff and fred in the example.org domain, they can give their email addresses to their friends as biff@example.org and fred@example.org. All email to both of these addresses will be delivered to the 'example' user. So we have two problems. 1) How do we sort out the email to different users and 2) How do we provide POP/IMAP access?

In the qmail-only case, we can create .qmail-* files for each user that deliver to a private maildir. In biff's case we could have:

/home/example/.qmail-biff:
/home/example/biff-maildir/

and in fred's case:

/home/example/.qmail-fred:
/home/example/fred-maildir/

The /home/example/.qmail-biff-default file would be a link to /home/example/.qmail-biff if you wanted to allow biff to receive, not only mail to biff@example.org, but also mail to biff-<anything>@example.org. The /home/example/.qmail-fred-default file is analogous.

You can see that managing these files would soon become overwhelming, especially with multiple domains. The virtual domain managers (VDMs) provide a solution. A /home/example/.qmail-default file is created (this is oversimplified; VPopMail works a little differently, but the idea is the same), which handles all addresses in the example.org domain. Each VDM comes with a delivery program that 1) runs from that .qmail-default file, 2) determines to which user the mail is directed and 3) delivers the mail to the appropriate user's maildir.

Both VDMs also provide a program that can authenticate a user/password combination as provided by the user's MUA. This makes it possible to set up a POP or IMAP server with authentication provided by the VDM. So by using one of the VDMs, you can have private, authenticated POP/IMAP mailboxes in one or more domains on a single mailhub.

VMailMgr implements virtual domains more or less as described. A separate UID is used for each domain. In a typical VPopMail installation, however, all virtual domains are under a single UID, usually 'vpopmail'. VPopMail then uses the qmail-users(5) mechanism to deliver all mail for a particular domain to the .qmail-default file found in a subdirectory named for the domain. This means you will find a .qmail-default file in each domain's directory:

/home/vpopmail/domains/example.org/.qmail-default

tmda-ofmipd and Virtual Domains

The tmda-ofmipd program has two command-line options to assist in running it in a virtual domain environment. The first is:

-S <script>
--vhome-script <script>

Each of the VDMs comes with a utility program that can provide the virtual user's home directory. In VPopMail's case, it is the directory that is named after the user and that contains the private Maildir directory. VMailMgr, on the other hand, names the maildir itself after the user account ('biff' rather than 'Maildir') and it is that maildir directory that we will consider the home directory under VMailMgr.

A simple script can parse the output of these utility programs and provide the full pathname of the home directory to tmda-ofmipd. Once we have the virtual user's home directory, we set the $HOME environment variable to that directory before running tmda-inject. From that point on, the '~' notation in TMDA's config file and filter files will work as expected, referring to the virtual home directory.

Two sample scripts are provided in the tmda/contrib directory, called vpopmail-vdir.sh and vmailmgr-vdir.sh, that will work in most installations. If you wish to store your users' TMDA configuration files somewhere other than <virtual_home_dir>/.tmda, you can easily write a different script.

You give the name of the script as the argument to this command line option. If this option is given on the command line, it signals to tmda-ofmipd that you are using virtual domains.

The second command line option is normally not necessary. Some Linux distributions, such as Debian, may need it, though. It is:

-v <path_to_qmails_virtualdomains_file>
--vdomains-path <path_to_qmails_virtualdomains_file>

This is the path to qmail's 'virtualdomains' file. Qmail is normally installed in /var/qmail and 'virtualdomains' is found in /var/qmail/control/virtualdomains. This is the location that tmda-ofmipd assumes, so if this is the correct path for your system, you don't need to set this option.

Some Linux distributions place qmail in /usr/local instead. If your qmail installation is not in /var/qmail, you will need to give this option to tmda-ofmipd and specify the full pathname of the qmail 'virtualdomains' file.

The rest of this HOWTO is divided into two sections: one for VPopMail and one for VMailMgr. Please read the appropriate one for your installation, as the configuration is somewhat different for each.

VPopMail

All files, including the per-user TMDA configuration, filter and log files, are owned by the vpopmail user. Therefore, you should run tmda-ofmipd as the vpopmail user. This does not mean that you should use the -u (--username) switch. If you do this, the VPopMail support will not work!

Instead, use 'su' or 'sudo' to start tmda-ofmipd as the vpopmail user. In the simplest case, as root, you can start tmda-ofmipd like this:

# su -l vpopmail -c '/usr/local/tmda/bin/tmda-ofmipd -S /usr/local/tmda/contrib/vpopmail-vdir.sh'

This assumes that the vpopmail user has a login shell. It also assumes the default authentication mechanism, where tmda-ofmipd searches the /home/vpopmail/.tmda/tofmipd file. You can use any of the other authentication options (vchkpw, POP/IMAP/LDAP/etc.) and, if you use the IP-based domains option in VPopMail, you can bind to all IP addresses on the machine by specifying '-p 0.0.0.0:8025'.

Be sure to create a .tmda subdirectory in each user's home directory. In a small VPopMail installation, this will typically be:

/home/vpopmail/domains/example.com/<username>/.tmda

Then, run tmda-keygen for each user, placing the generated key in .tmda/crypt_key as usual.

Alternately, TMDA can be automatically added to VPopMail accounts using the vadduser-tmda script. Installation and usage instructions are listed in the top of the script, which can be found in the contrib directory of the TMDA source.

If you are willing to use TMDA's default file locations for filters, you can create a simple /etc/tmdarc and avoid creating and maintaining individual user .tmda/config files. Here's an example:

/etc/tmdarc:
import os

CONFIRM_APPEND = os.path.expanduser("~/.tmda/whitelist")

Finally, create an outgoing filter file, '~/.tmda/filters/outgoing'. The default outgoing action is 'dated'. A simple filter for a typical virtual user might look something like this:

~/.tmda/filters/outgoing:
to-file ~/.tmda/whitelist bare

This will cause email to all addresses in the whitelist to be sent with a 'bare' From header field. Any addresses not found in the whitelist will have a 'dated' From field.

Please report any problems with the VPopMail support to the tmda-workers@tmda.net mailing list.

VMailMgr

Since each virtual domain is under the control of a different system UID in the VMailMgr model, you should run tmda-ofmipd as root, so that it can setuid to the correct user before running tmda-inject. A typical command line might be:
# /usr/local/tmda/bin/tmda-ofmipd -S /usr/local/tmda/contrib/vmailmgr-vdir.sh

This assumes the default authentication mechanism, where tmda-ofmipd searches the /etc/tofmipd file. You can use any of the other authentication options (vchkpw, POP/IMAP/LDAP/etc.) and, if you use IP-based domains, you can bind to all IP addresses on the machine by specifying '-p 0.0.0.0:8025'.

In a VMailMgr configuration, the system user that controls the virtual domain has a home directory, e.g. for a username of 'example.com', the home directory would typically be /home/example.com. In that directory is a 'users' subdirectory that contains a maildir for each user with the same name as the user's email address: for instance, /home/example.com/users/biff. As mentioned above, the directory that tmda-ofmipd considers to be the user's home directory is the actual maildir.

Be sure to create a .tmda subdirectory in each user's home directory. In a typical VMailMgr installation, this will be:

/home/example.com/users/<username>/.tmda

Then, run tmda-keygen for each user, placing the generated key in <username>/.tmda/crypt_key as usual.

If you are willing to use TMDA's default file locations for filters, you can create a simple /etc/tmdarc and avoid creating and maintaining individual user .tmda/config files. Here's an example:

/etc/tmdarc:
import os

CONFIRM_APPEND = os.path.expanduser("~/.tmda/whitelist")

Finally, create an outgoing filter file, '~/.tmda/filters/outgoing'. The default outgoing action is 'dated'. A simple filter for a typical virtual user might look something like this:

~/.tmda/filters/outgoing:
to-file ~/.tmda/whitelist bare

This will cause email to all addresses in the whitelist to be sent with a 'bare' From header field. Any addresses not found in the whitelist will have a 'dated' From field.

Please report any problems with the VMailMgr support to the tmda-workers@tmda.net mailing list.