CVS: tmda/htdocs tmda-vdomains.ht,1.3,1.4 tmda-vdomains.html,1.12,1.13
Timothy Legant <[email protected]>
| Newsgroups | gmane.mail.spam.tmda.cvs |
|---|---|
| Message-ID | <[email protected]> |
Update of /cvsroot/tmda/tmda/htdocs In directory sc8-pr-cvs1:/tmp/cvs-serv32566/htdocs Modified Files: tmda-vdomains.ht tmda-vdomains.html Log Message: Removed a lot of babble. Added information on the new capability of tmda-filter to work with virtual domains. Fixed the two internal links so they actually work. Index: tmda-vdomains.ht =================================================================== RCS file: /cvsroot/tmda/tmda/htdocs/tmda-vdomains.ht,v retrieving revision 1.3 retrieving revision 1.4 diff -u -r1.3 -r1.4 --- tmda-vdomains.ht 24 Apr 2003 19:29:26 -0000 1.3 +++ tmda-vdomains.ht 5 Jul 2003 00:27:37 -0000 1.4 @@ -13,112 +13,125 @@ <h2>Virtual Domains Background</h2> -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. +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. <p> -In the simple case, the name of the domain, say example.org, is placed -in qmail's 'virtualdomains' file followed by a colon (<b>:</b>) 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'. +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. <p> -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. +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. <p> -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. +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. <p> -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 [email protected] and [email protected]. 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? +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. <p> -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: +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. <p> -<i>/home/example/.qmail-biff</i>:<br> -<code> -/home/example/biff-maildir/ -</code> +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. <p> -and in fred's case: +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. -<p> +<h2>tmda-filter</h2> -<i>/home/example/.qmail-fred</i>:<br> -<code> -/home/example/fred-maildir/ -</code> +The tmda-filter program has a command-line option for use with virtual +domains. <p> -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 [email protected], but also mail to -biff-<anything>@example.org. The -/home/example/.qmail-fred-default file is analogous. +<blockquote><code> +-S <script><br> +--vhome-script <script> +</code></blockquote> <p> -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. +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. <p> -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. +Because of this processing, you no longer need to explicitly specify +the user's configuration file and therefore you do not need separate +.qmail-<user> and .qmail-<user>-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. <p> -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: +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: <p> +<i>.qmail-default</i>:<br> <code> -/home/vpopmail/domains/example.org/.qmail-default +| preline tmda-filter -S ~vpopmail/bin/vpopmail-vdir.sh<br> +| vdelivermail "" bounce-no-mailbox </code> -<h2>tmda-ofmipd and Virtual Domains</h2> + +<h2>tmda-ofmipd</h2> The tmda-ofmipd program has two command-line options to assist in running it in a virtual domain environment. The first is: @@ -132,36 +145,10 @@ <p> -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. - -<p> - -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. - -<p> - -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. - -<p> - -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. +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. <p> @@ -192,9 +179,9 @@ <p> -The rest of this HOWTO is divided into two sections: one for <a -href="vpopmail">VPopMail</a> and one for <a -href="vmailmgr">VMailMgr</a>. Please read the appropriate one for +The rest of this HOWTO is about tmda-ofmipd and is divided into two +sections: one for <a href="#vpopmail">VPopMail</a> and one for <a +href="#vmailmgr">VMailMgr</a>. Please read the appropriate one for your installation, as the configuration is somewhat different for each. @@ -202,9 +189,8 @@ 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! +tmda-ofmipd as the vpopmail user. <b>Do NOT use the -u (--username) +switch</b>. If you do this, the VPopMail support will not work! <p> @@ -213,7 +199,7 @@ this: <code><pre> -# su -l vpopmail -c '/usr/local/tmda/bin/tmda-ofmipd -S /usr/local/tmda/contrib/vpopmail-vdir.sh' +# su -l vpopmail -c '/path/to/tmda-ofmipd -S /path/to/vpopmail-vdir.sh' </pre></code> <p> @@ -227,8 +213,9 @@ <p> -Be sure to create a .tmda subdirectory in each user's home directory. -In a small VPopMail installation, this will typically be: +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: <p> @@ -242,6 +229,7 @@ .tmda/crypt_key as usual. <p> + 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 @@ -249,7 +237,7 @@ <p> -If you are willing to use TMDA's default file locations for filters, +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: @@ -259,27 +247,34 @@ <code> import os<br> <br> +BARE_APPEND = os.path.expanduser("~/.tmda/whitelist")<br> CONFIRM_APPEND = os.path.expanduser("~/.tmda/whitelist") </code> <p> 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: +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: <p> <i>~/.tmda/filters/outgoing</i>:<br> <code> -to-file ~/.tmda/whitelist bare +to-file ~/.tmda/whitelist bare<br> +to * tag envelope dated=10d from bare </code> <p> 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. +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. <p> @@ -294,14 +289,14 @@ typical command line might be: <code><pre> -# /usr/local/tmda/bin/tmda-ofmipd -S /usr/local/tmda/contrib/vmailmgr-vdir.sh +# /path/to/tmda-ofmipd -S /path/to/vmailmgr-vdir.sh </pre></code> <p> 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 +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'. @@ -309,17 +304,18 @@ 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 +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. <p> -Be sure to create a .tmda subdirectory in each user's home directory. -In a typical VMailMgr installation, this will be: +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: <p> @@ -330,12 +326,12 @@ <p> Then, run tmda-keygen for each user, placing the generated key in -<username>/.tmda/crypt_key as usual. +users/<username>/.tmda/crypt_key as usual. <p> -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 +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: <p> @@ -344,27 +340,34 @@ <code> import os<br> <br> +BARE_APPEND = os.path.expanduser("~/.tmda/whitelist")<br> CONFIRM_APPEND = os.path.expanduser("~/.tmda/whitelist") </code> <p> 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: +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: <p> <i>~/.tmda/filters/outgoing</i>:<br> <code> -to-file ~/.tmda/whitelist bare +to-file ~/.tmda/whitelist bare<br> +to * tag envelope dated=10d from bare </code> <p> 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. +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. <p> Index: tmda-vdomains.html =================================================================== RCS file: /cvsroot/tmda/tmda/htdocs/tmda-vdomains.html,v retrieving revision 1.12 retrieving revision 1.13 diff -u -r1.12 -r1.13 --- tmda-vdomains.html 3 Jul 2003 20:36:40 -0000 1.12 +++ tmda-vdomains.html 5 Jul 2003 00:27:37 -0000 1.13 @@ -1,191 +1,186 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> -<html> +<HTML> <!-- THIS PAGE IS AUTOMATICALLY GENERATED. DO NOT EDIT. --> -<!-- Thu Jul 3 14:34:22 2003 --> -<!-- USING HT2HTML 2.0 --> -<!-- SEE http://ht2html.sf.net --> +<!-- Fri Jul 4 18:59:42 2003 --> +<!-- USING HT2HTML 1.2 --> +<!-- SEE http://barry.wooz.org/software/ht2html --> <!-- User-specified headers: Title: tmda-ofmipd + VPopMail/VMailMgr HOWTO --> -<head> -<title>tmda-ofmipd + VPopMail/VMailMgr HOWTO</title> -<meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> -<meta name="generator" content="HT2HTML/2.0"> -<style type="text/css"> -body { margin: 0px; } -</style> -</head> -<body bgcolor="#ffffff" text="#000000" - marginwidth="0" marginheight="0" - link="#0000bb" vlink="#551a8b" - alink="#ff0000"> +<HEAD> +<TITLE>tmda-ofmipd + VPopMail/VMailMgr HOWTO</TITLE> + +</HEAD> +<BODY BGCOLOR="#ffffff" TEXT="#000000" + TOPMARGIN="0" LEFTMARGIN="0" MARGINWIDTH="0" MARGINHEIGHT="0" + LINK="#0000bb" VLINK="#551a8b" + ALINK="#ff0000"> <!-- start of page table --> -<table width="100%" border="0" cellspacing="0" cellpadding="0"> +<TABLE WIDTH="100%" BORDER=0 CELLSPACING=0 CELLPADDING=0> <!-- start of banner row --> -<tr> +<TR> <!-- start of corner cells --> -<td width="150" valign="middle" bgcolor="#afeeee" class="corner"> +<TD WIDTH=150 VALIGN=CENTER BGCOLOR="#afeeee"> <center><font size="+2" - >>>> TMDA </font></center> </td> -<td width="15" bgcolor="#cccccc"> </td><!--spacer--> + >>>> TMDA </font></center> </TD> +<TD WIDTH=15 BGCOLOR="#cccccc"> </TD><!--spacer--> <!-- end of corner cells --> <!-- start of banner --> -<td width="90%" bgcolor="#cccccc" class="banner"> +<TD WIDTH="90%" BGCOLOR="#cccccc"> <!-- start of site links table --> -<table width="100%" border="0" +<TABLE WIDTH="100%" BORDER=0 CELLSPACING=0 CELLPADDING=0 - bgcolor="#ffffff"> -<tr> - <td bgcolor="#cccccc"> + COLS=4 ROWS=1 BGCOLOR="#ffffff"> +<TR> + <TD BGCOLOR="#cccccc"> <a href="./index.html">TMDA Homepage</a><br>[ <a href="http://www.au.tmda.net/">AU</a> | <a href="http://www.us.tmda.net/">US</a> mirror ] - </td> - <td bgcolor="#cccccc"> + </TD> + <TD BGCOLOR="#cccccc"> <a href="./tmda-cgi">tmda-cgi</a> - </td> - <td bgcolor="#cccccc"> + </TD> + <TD BGCOLOR="#cccccc"> <a href="http://sourceforge.net/projects/tmda">TMDA @ SourceForge</a> - </td> - <td bgcolor="#cccccc"> - </td> -</tr> -</table><!-- end of site links table --> - -</td><!-- end of banner --> -</tr><!-- end of banner row --> -<tr><!-- start of sidebar/body row --> + </TD> + <TD BGCOLOR="#cccccc"> + </TD> +</TR> +</TABLE><!-- end of site links table --> + +</TD><!-- end of banner --> +</TR><!-- end of banner row --> +<TR><!-- start of sidebar/body row --> <!-- start of sidebar cells --> -<td width="150" valign="top" bgcolor="#cccccc" class="sidebar"> +<TD WIDTH=150 VALIGN=TOP BGCOLOR="#cccccc"> <!-- start of sidebar table --> -<table width="100%" border="0" cellspacing="0" cellpadding="3" - bgcolor="#ffffff"> -<tr><td bgcolor="#191970"><b><font color="#ffffff"> +<TABLE WIDTH="100%" BORDER=0 CELLSPACING=0 CELLPADDING=3 + BGCOLOR="#ffffff"> +<TR><TD BGCOLOR="#191970"><B><FONT COLOR="#ffffff"> Overview -</font></b></td></tr> -<tr><td bgcolor="#cccccc"> -<a href="index.html">Introduction</a> -</td></tr> -<tr><td bgcolor="#cccccc"> -<a href="history.html">History</a> -</td></tr> -<tr><td bgcolor="#cccccc"> -<a href="features.html">Features</a> -</td></tr> -<tr><td bgcolor="#cccccc"> -<a href="results.html">Results & Testimonials</a> -</td></tr> -<tr><td bgcolor="#cccccc"> -<a href="inuse.html">TMDA In Use</a> -</td></tr> -<tr><td bgcolor="#cccccc"> -<a href="press.html">Press Coverage</a><!-- -*- html -*- --> -</td></tr> -<tr><td bgcolor="#cccccc"> -<tr><td bgcolor="#191970"><b><font color="#ffffff"> +</FONT></B></TD></TR> +<TR><TD BGCOLOR="#cccccc"> +<A HREF="index.html">Introduction</A> +</TD></TR> +<TR><TD BGCOLOR="#cccccc"> +<A HREF="history.html">History</A> +</TD></TR> +<TR><TD BGCOLOR="#cccccc"> +<A HREF="features.html">Features</A> +</TD></TR> +<TR><TD BGCOLOR="#cccccc"> +<A HREF="results.html">Results & Testimonials</A> +</TD></TR> +<TR><TD BGCOLOR="#cccccc"> +<A HREF="inuse.html">TMDA In Use</A> +</TD></TR> +<TR><TD BGCOLOR="#cccccc"> +<A HREF="press.html">Press Coverage</A><!-- -*- html -*- --> +</TD></TR> +<TR><TD BGCOLOR="#cccccc"> +<TR><TD BGCOLOR="#191970"><B><FONT COLOR="#ffffff"> Install -</font></b></td></tr> -<tr><td bgcolor="#cccccc"> -<a href="requirements.html">Requirements</a> -</td></tr> -<tr><td bgcolor="#cccccc"> -<a href="download.html">Download</a> -</td></tr> -<tr><td bgcolor="#cccccc"> -<a href="install.html">Installation</a> -</td></tr> -<tr><td bgcolor="#cccccc"> -<a href="upgrade.html">Upgrading</a> -</td></tr> -<tr><td bgcolor="#cccccc"> -<tr><td bgcolor="#191970"><b><font color="#ffffff"> +</FONT></B></TD></TR> +<TR><TD BGCOLOR="#cccccc"> +<A HREF="requirements.html">Requirements</A> +</TD></TR> +<TR><TD BGCOLOR="#cccccc"> +<A HREF="download.html">Download</A> +</TD></TR> +<TR><TD BGCOLOR="#cccccc"> +<A HREF="install.html">Installation</A> +</TD></TR> +<TR><TD BGCOLOR="#cccccc"> +<A HREF="upgrade.html">Upgrading</A> +</TD></TR> +<TR><TD BGCOLOR="#cccccc"> +<TR><TD BGCOLOR="#191970"><B><FONT COLOR="#ffffff"> Configuration -</font></b></td></tr> -<tr><td bgcolor="#cccccc"> -<a href="config.html">Overview</a> -</td></tr> -<tr><td bgcolor="#cccccc"> -<a href="config-pre.html">Pre-Configuration</a> -</td></tr> -<tr><td bgcolor="#cccccc"> -<a href="config-server.html">Server Configuration</a> -</td></tr> -<tr><td bgcolor="#cccccc"> -<a href="config-client.html">Client Configuration</a> -</td></tr> -<tr><td bgcolor="#cccccc"> -<a href="config-vars.html">Configuration Variables</a> -</td></tr> -<tr><td bgcolor="#cccccc"> -<a href="config-filter.html">Filter Specification</a> -</td></tr> -<tr><td bgcolor="#cccccc"> -<a href="filter-sources.html">Filter Sources</a> -</td></tr> -<tr><td bgcolor="#cccccc"> -<tr><td bgcolor="#191970"><b><font color="#ffffff"> +</FONT></B></TD></TR> +<TR><TD BGCOLOR="#cccccc"> +<A HREF="config.html">Overview</A> +</TD></TR> +<TR><TD BGCOLOR="#cccccc"> +<A HREF="config-pre.html">Pre-Configuration</A> +</TD></TR> +<TR><TD BGCOLOR="#cccccc"> +<A HREF="config-server.html">Server Configuration</A> +</TD></TR> +<TR><TD BGCOLOR="#cccccc"> +<A HREF="config-client.html">Client Configuration</A> +</TD></TR> +<TR><TD BGCOLOR="#cccccc"> +<A HREF="config-vars.html">Configuration Variables</A> +</TD></TR> +<TR><TD BGCOLOR="#cccccc"> +<A HREF="config-filter.html">Filter Specification</A> +</TD></TR> +<TR><TD BGCOLOR="#cccccc"> +<A HREF="filter-sources.html">Filter Sources</A> +</TD></TR> +<TR><TD BGCOLOR="#cccccc"> +<TR><TD BGCOLOR="#191970"><B><FONT COLOR="#ffffff"> HOWTOs -</font></b></td></tr> -<tr><td bgcolor="#cccccc"> -<a href="howtos.html">Overview</a> -</td></tr> -<tr><td bgcolor="#cccccc"> -<a href="howto-template.html">Templates</a> -</td></tr> -<tr><td bgcolor="#cccccc"> -<a href="tmda-ofmipd.html">tmda-ofmipd</a> -</td></tr> -<tr><td bgcolor="#cccccc"> +</FONT></B></TD></TR> +<TR><TD BGCOLOR="#cccccc"> +<A HREF="howtos.html">Overview</A> +</TD></TR> +<TR><TD BGCOLOR="#cccccc"> +<A HREF="howto-template.html">Templates</A> +</TD></TR> +<TR><TD BGCOLOR="#cccccc"> +<A HREF="tmda-ofmipd.html">tmda-ofmipd</A> +</TD></TR> +<TR><TD BGCOLOR="#cccccc"> <b>Virtual Domains</b> -</td></tr> -<tr><td bgcolor="#cccccc"> -<tr><td bgcolor="#191970"><b><font color="#ffffff"> +</TD></TR> +<TR><TD BGCOLOR="#cccccc"> +<TR><TD BGCOLOR="#191970"><B><FONT COLOR="#ffffff"> Support -</font></b></td></tr> -<tr><td bgcolor="#cccccc"> -<a href="trouble.html">Troubleshooting</a> -</td></tr> -<tr><td bgcolor="#cccccc"> +</FONT></B></TD></TR> +<TR><TD BGCOLOR="#cccccc"> +<A HREF="trouble.html">Troubleshooting</A> +</TD></TR> +<TR><TD BGCOLOR="#cccccc"> <a href="http://tmda.net/faq.cgi" TARGET="Resource Window">FAQ</a> -</td></tr> -<tr><td bgcolor="#cccccc"> -<a href="bugs.html">Bugs & Patches</a> -</td></tr> -<tr><td bgcolor="#cccccc"> +</TD></TR> +<TR><TD BGCOLOR="#cccccc"> +<A HREF="bugs.html">Bugs & Patches</A> +</TD></TR> +<TR><TD BGCOLOR="#cccccc"> <a href="http://tmda.net/lists/listinfo/" TARGET="Resource Window">Mailing Lists</a> -</td></tr> -<tr><td bgcolor="#cccccc"> +</TD></TR> +<TR><TD BGCOLOR="#cccccc"> <a href="http://mla.libertine.org/" TARGET="Resource Window">List Archive</a> -</td></tr> -<tr><td bgcolor="#cccccc"> -<a href="support-commercial.html">Commercial Support</a> -</td></tr> -<tr><td bgcolor="#cccccc"> -<a href="resources.html">External Resources</a> -</td></tr> -<tr><td bgcolor="#cccccc"> -<a href="mirrors.html">Mirrors</a> -</td></tr> -<tr><td bgcolor="#cccccc"> -<tr><td bgcolor="#191970"><b><font color="#ffffff"> +</TD></TR> +<TR><TD BGCOLOR="#cccccc"> +<A HREF="support-commercial.html">Commercial Support</A> +</TD></TR> +<TR><TD BGCOLOR="#cccccc"> +<A HREF="resources.html">External Resources</A> +</TD></TR> +<TR><TD BGCOLOR="#cccccc"> +<A HREF="mirrors.html">Mirrors</A> +</TD></TR> +<TR><TD BGCOLOR="#cccccc"> +<TR><TD BGCOLOR="#191970"><B><FONT COLOR="#ffffff"> Author -</font></b></td></tr> -<tr><td bgcolor="#cccccc"> -<a href="mailto:[email protected]">Jason R. Mastaler</a> -</td></tr> -<tr><td bgcolor="#cccccc"> +</FONT></B></TD></TR> +<TR><TD BGCOLOR="#cccccc"> +<A HREF="mailto:[email protected]">Jason R. Mastaler</A> +</TD></TR> +<TR><TD BGCOLOR="#cccccc"> -</td></tr> -<tr><td bgcolor="#cccccc"> +</TD></TR> +<TR><TD BGCOLOR="#cccccc"> © 2001-2003 -</td></tr> -</table><!-- end of sidebar table --> +</TD></TR> +</TABLE><!-- end of sidebar table --> -</td> -<td width="15"> </td><!--spacer--> +</TD> +<TD WIDTH=15> </TD><!--spacer--> <!-- end of sidebar cell --> <!-- start of body cell --> -<td valign="top" width="90%" class="body"><br> +<TD VALIGN=TOP WIDTH="90%"><BR> <h1>tmda-ofmipd + VPopMail or VMailMgr</h1> <hr> @@ -199,112 +194,125 @@ <h2>Virtual Domains Background</h2> -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. +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. <p> -In the simple case, the name of the domain, say example.org, is placed -in qmail's 'virtualdomains' file followed by a colon (<b>:</b>) 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'. +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. <p> -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. +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. <p> -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. +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. <p> -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 [email protected] and [email protected]. 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? +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. <p> -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: +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. <p> -<i>/home/example/.qmail-biff</i>:<br> -<code> -/home/example/biff-maildir/ -</code> +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. <p> -and in fred's case: +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. -<p> +<h2>tmda-filter</h2> -<i>/home/example/.qmail-fred</i>:<br> -<code> -/home/example/fred-maildir/ -</code> +The tmda-filter program has a command-line option for use with virtual +domains. <p> -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 [email protected], but also mail to -biff-<anything>@example.org. The -/home/example/.qmail-fred-default file is analogous. +<blockquote><code> +-S <script><br> +--vhome-script <script> +</code></blockquote> <p> -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. +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. <p> -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. +Because of this processing, you no longer need to explicitly specify +the user's configuration file and therefore you do not need separate +.qmail-<user> and .qmail-<user>-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. <p> -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: +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: <p> +<i>.qmail-default</i>:<br> <code> -/home/vpopmail/domains/example.org/.qmail-default +| preline tmda-filter -S ~vpopmail/bin/vpopmail-vdir.sh<br> +| vdelivermail "" bounce-no-mailbox </code> -<h2>tmda-ofmipd and Virtual Domains</h2> + +<h2>tmda-ofmipd</h2> The tmda-ofmipd program has two command-line options to assist in running it in a virtual domain environment. The first is: @@ -318,36 +326,10 @@ <p> -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. - -<p> - -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. - -<p> - -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. - -<p> - -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. +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. <p> @@ -378,9 +360,9 @@ <p> -The rest of this HOWTO is divided into two sections: one for <a -href="vpopmail">VPopMail</a> and one for <a -href="vmailmgr">VMailMgr</a>. Please read the appropriate one for +The rest of this HOWTO is about tmda-ofmipd and is divided into two +sections: one for <a href="#vpopmail">VPopMail</a> and one for <a +href="#vmailmgr">VMailMgr</a>. Please read the appropriate one for your installation, as the configuration is somewhat different for each. @@ -388,9 +370,8 @@ 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! +tmda-ofmipd as the vpopmail user. <b>Do NOT use the -u (--username) +switch</b>. If you do this, the VPopMail support will not work! <p> @@ -399,7 +380,7 @@ this: <code><pre> -# su -l vpopmail -c '/usr/local/tmda/bin/tmda-ofmipd -S /usr/local/tmda/contrib/vpopmail-vdir.sh' +# su -l vpopmail -c '/path/to/tmda-ofmipd -S /path/to/vpopmail-vdir.sh' </pre></code> <p> @@ -413,8 +394,9 @@ <p> -Be sure to create a .tmda subdirectory in each user's home directory. -In a small VPopMail installation, this will typically be: +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: <p> @@ -428,6 +410,7 @@ .tmda/crypt_key as usual. <p> + 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 @@ -435,7 +418,7 @@ <p> -If you are willing to use TMDA's default file locations for filters, +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: @@ -445,27 +428,34 @@ <code> import os<br> <br> +BARE_APPEND = os.path.expanduser("~/.tmda/whitelist")<br> CONFIRM_APPEND = os.path.expanduser("~/.tmda/whitelist") </code> <p> 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: +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: <p> <i>~/.tmda/filters/outgoing</i>:<br> <code> -to-file ~/.tmda/whitelist bare +to-file ~/.tmda/whitelist bare<br> +to * tag envelope dated=10d from bare </code> <p> 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. +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. <p> @@ -480,14 +470,14 @@ typical command line might be: <code><pre> -# /usr/local/tmda/bin/tmda-ofmipd -S /usr/local/tmda/contrib/vmailmgr-vdir.sh +# /path/to/tmda-ofmipd -S /path/to/vmailmgr-vdir.sh </pre></code> <p> 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 +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'. @@ -495,17 +485,18 @@ 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 +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. <p> -Be sure to create a .tmda subdirectory in each user's home directory. -In a typical VMailMgr installation, this will be: +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: <p> @@ -516,12 +507,12 @@ <p> Then, run tmda-keygen for each user, placing the generated key in -<username>/.tmda/crypt_key as usual. +users/<username>/.tmda/crypt_key as usual. <p> -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 +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: <p> @@ -530,34 +521,41 @@ <code> import os<br> <br> +BARE_APPEND = os.path.expanduser("~/.tmda/whitelist")<br> CONFIRM_APPEND = os.path.expanduser("~/.tmda/whitelist") </code> <p> 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: +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: <p> <i>~/.tmda/filters/outgoing</i>:<br> <code> -to-file ~/.tmda/whitelist bare +to-file ~/.tmda/whitelist bare<br> +to * tag envelope dated=10d from bare </code> <p> 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. +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. <p> Please report any problems with the VMailMgr support to the [email protected] mailing list. -</td><!-- end of body cell --> -</tr><!-- end of sidebar/body row --> -</table><!-- end of page table --> -</body></html> +</TD><!-- end of body cell --> +</TR><!-- end of sidebar/body row --> +</TABLE><!-- end of page table --> +</BODY></HTML> _______________________________________ tmda-cvs mailing list http://tmda.net/lists/listinfo/tmda-cvs