| [FrontPage] [TitleIndex] [WordIndex]

# VirtualDomainsHowto

## 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.

### 1. Virtual Domains Background

Virtual domains are a neat feature of qmail where a single UID 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 VPopMail's case, a single UID can be used for all of the virtual domains on the system.

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

Both virtual domain managers (VDMs) come with 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 using a separate UID for each domain. VPopMail can do the same, but in a typical installation all virtual domains are under a single UID, often 'vpopmail'. Normal mail delivery is accomplished in either case through a .qmail-default file and a custom delivery program that is part of the VDM package.

Each of the VDMs also comes with a utility program that can provide the path to the virtual user's home directory. In VPopMail's case, the home directory is named for the user and contains the private Maildir directory. VMailMgr, on the other hand, names the maildir itself after the user account ('tim' rather than 'Maildir') and it is that maildir directory that TMDA uses as the home directory under VMailMgr.

A simple script can parse the output of these utility programs and print the virtual user's home directory. The output of the script is captured by either tmda-filter or tmda-ofmipd and used to set the $HOME environment variable. From that point on, the '~' notation in TMDA's config file and filter files will refer to the virtual user's home directory.

This means that the default settings for many of TMDA's configuration variables will work naturally in a virtual domain environment. TMDA will expect to find each user's .tmda/ directory in the $HOME directory. There is no need to set DATADIR, FILTER_INCOMING or FILTER_OUTGOING, for example, if you are satisfied with the default path settings.

Two sample scripts are provided in the tmda/contrib directory, called vpopmail-vdir.sh and vmailmgr-vdir.sh, which 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.

### 2. tmda-filter

The tmda-filter program has a command-line option for use with virtual domains.

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

You give the name of the script that prints the virtual user's home directory as the argument to this option. tmda-filter will use the output of the script to set $HOME before either Defaults.py or the user's config file are loaded, thus ensuring that tilde (~) expansion refers to the correct home directory.

Because of this processing, you no longer need to explicitly specify the user's configuration file and therefore you do not need separate .qmail- and .qmail--default files. All users can be handled from the .qmail-default file installed by VPopMail or VMailMgr. Of course, if you expect that only some of your users will use TMDA, you will need to leave the .qmail-default file alone and create separate files for those users who use TMDA.

Finally, tmda-filter may be unable to find the user's home directory. For example, this will be the case for mail sent to a bogus address in the domain. If tmda-filter is unable to find the user, it will exit with a 0 return code, allowing further processing in the .qmail-* files to occur. It is recommended that you leave the DELIVERY configuration variable set to the default ('_qok_') and place the VDMs delivery program after the line that runs tmda-filter. VPopMail example:

.qmail-default
`| preline tmda-filter -S ~vpopmail/bin/vpopmail-vdir.sh`
`| vdelivermail "" bounce-no-mailbox`

### 3. tmda-ofmipd

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>`

This works the same way as the corresponding option for tmda-filter. Setting it to a script that prints the virtual user's home directory will cause tmda-ofmipd to set the $HOME directory before running tmda-inject to process and send the mail.

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 about tmda-ofmipd and 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.

### 4. Use of tmda-pending

There are two ways of using tmda-pending: through the tmda-cgi interface, or via the command line. This section describes use of tmda-pending via the command line.

Normally, a virtual user does not have a shell account on the machine hosting the mail service. In some cases, however, you may want to be able to browse the pending queue for a user as a super-user (root, vpopmail...), or perhaps provide some kind of custom service executed as uid super-user.

To do so, you need to run tmda-pending as follows:

`tmda-pending --config-file=/path/to/virtual/user/config`

In the config file, be sure that the following is set:

`CRYPT_KEY_FILE = "/home/vpopmail/domains/leangen.net/dleangen/.tmda/crypt_key"`

To be able to browse the contents of a message, tmda-pending needs to know how to locate a "scrolling" application. For example, to set the application to less, ensure that you set an environment variable such as follows (or whatever works on your system):

`export PAGER=/usr/bin/less`

### 5. 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. Do NOT 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 '/path/to/tmda-ofmipd -S /path/to/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'.

For each user, be sure to create a .tmda/ subdirectory in the directory printed by the --vhome-script. In a normal VPopMail/TMDA 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 satisfied with 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`
`BARE_APPEND = "~/.tmda/whitelist"`
`CONFIRM_APPEND = "~/.tmda/whitelist"`

Finally, create an outgoing filter file, '~/.tmda/filters/outgoing'. The default outgoing action is 'dated'. You may want to use a default of 'bare'. You can either set ACTION_OUTGOING to 'bare' in the user's config or /etc/tmdarc or you can tag the messages in the outgoing filter. A simple filter allowing the user to receive bounces and using the latter technique to leave the user's From: header untagged might look something like this:

~/.tmda/filters/outgoing:

`to-file ~/.tmda/whitelist bare`
`to * tag envelope dated=10d from bare`

This will cause email to all addresses in the whitelist to be sent with a 'bare' From: header field. Unknown address will also be sent with a 'bare' From: field and will tag the envelope sender with a dated address so that bounces do not get stuck in the pending queue.

### 6. 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:

`# /path/to/tmda-ofmipd -S /path/to/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 (checkvpw, 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 might 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/tim. As mentioned above, the directory that tmda-ofmipd considers to be the user's home directory is the actual maildir.

For each user, be sure to create a .tmda subdirectory in the directory printed by the --vhome-script. In a typical VMailMgr/TMDA installation, this might be:

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

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

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

/etc/tmdarc:

`import os`
`BARE_APPEND = "~/.tmda/whitelist"`
`CONFIRM_APPEND = "~/.tmda/whitelist"`

Finally, create an outgoing filter file, '~/.tmda/filters/outgoing'. The default outgoing action is 'dated'. You may want to use a default of 'bare'. You can either set ACTION_OUTGOING to 'bare' in the user's config or /etc/tmdarc or you can tag the messages in the outgoing filter. A simple filter allowing the user to receive bounces and using the latter technique to leave the user's From: header untagged might look something like this:

~/.tmda/filters/outgoing:

`to-file ~/.tmda/whitelist bare`
`to * tag envelope dated=10d from bare`

This will cause email to all addresses in the whitelist to be sent with a 'bare' From: header field. Unknown address will also be sent with a 'bare' From: field and will tag the envelope sender with a dated address so that bounces do not get stuck in the pending queue.

2007-07-30 15:45