|
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> |
|
2 <HTML> |
|
3 <HEAD> |
|
4 <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9"> |
|
5 <TITLE> VMailMgr HOWTO</TITLE> |
|
6 |
|
7 |
|
8 </HEAD> |
|
9 <BODY> |
|
10 <H1> VMailMgr HOWTO</H1> |
|
11 |
|
12 <H2>Bruce Guenter |
|
13 <A HREF="mailto:bruceg@em.ca">mailto:bruceg@em.ca</A>, |
|
14 Dan Kuykendall |
|
15 <A HREF="mailto:dan@kuykendall.org">mailto:dan@kuykendall.org</A></H2> v1.w, 2000-09-15 |
|
16 <P><HR> |
|
17 <EM> This document explains how to setup VMailMgr support pop3 virtual domain services in conjunction with Qmail.</EM> |
|
18 <HR> |
|
19 <H2><A NAME="s1">1. Introduction</A></H2> |
|
20 |
|
21 <P>VMailMgr (short for Virtual MAIL ManaGeR) is a package of programs |
|
22 designed to manage multiple domains of mail addresses and mailboxes |
|
23 on a single host. It co-operates with qmail for mail delivery and |
|
24 program control. |
|
25 <H2>1.1 What is VMailMgr and why should I use it?</H2> |
|
26 |
|
27 <P>VMailMgr is: |
|
28 <P> A series of utilities for managing virtual domains |
|
29 which include a password checking interface for qmail which replaces |
|
30 the usual checkpassword, and an authentication module for Courier |
|
31 IMAP, that provide access to the virtual mailboxes by one of three |
|
32 methods: |
|
33 <UL> |
|
34 <LI> IP-based virtual server access (invisible to the POP3 user)</LI> |
|
35 <LI> username-based access (username-virtualuser)</LI> |
|
36 <LI> hostname-based access (virtualuser@virtual.host or |
|
37 virtualuser:virtual.host)</LI> |
|
38 </UL> |
|
39 <P>You should use it if you prefer to have each domain controlled by a |
|
40 seperate username, allowing the use of system quotas and better |
|
41 security |
|
42 <H2>1.2 New versions </H2> |
|
43 |
|
44 <P>The newest version of this can be found on the VMailMgr homepage |
|
45 <A HREF="http://www.vmailmgr.org/">http://www.vmailmgr.org/</A> in its HTML version as well as |
|
46 in the source package SGML source, HTML, and text. Other versions |
|
47 may be found in different formats at the LDP homepage |
|
48 <A HREF="http://www.linuxdoc.org/">http://www.linuxdoc.org/</A>. |
|
49 <H2>1.3 Comments </H2> |
|
50 |
|
51 <P>Comments on this HOWTO should be directed to the VMailMgr mailing |
|
52 list. To subscribe, send an email to |
|
53 <A HREF="mailto:vmailmgr-subscribe@lists.em.ca">vmailmgr-subscribe@lists.em.ca</A>. |
|
54 <H2>1.4 History </H2> |
|
55 |
|
56 <P>This document was started by Bruce Guenter and reworked by Dan |
|
57 Kuykendall. |
|
58 <H2>1.5 Copyrights and Trademarks </H2> |
|
59 |
|
60 <P>Copyright (c) Dan Kuykendall. |
|
61 Permission is granted to copy, distribute and/or modify this document |
|
62 under the terms of the GNU Free Documentation License, Version 1.1 |
|
63 or any later version published by the Free Software Foundation |
|
64 <P>A copy of the license is available at |
|
65 <A HREF="http://www.gnu.org/copyleft/fdl.txt">GNU Free Documentation License</A>. |
|
66 <H2>1.6 Acknowledgements and Thanks </H2> |
|
67 |
|
68 <P>Thanks to Bruce Guenter for VMailMgr and the core of this |
|
69 HOWTO. Thanks to Mike Bell, who always seems to have the answers to |
|
70 my questions. Finally, thanks to all those on the |
|
71 <A HREF="mailto:vmailmgr@lists.em.ca">vmailmgr@lists.em.ca</A> |
|
72 mailing list who have helped me, or asked the same stuff so many |
|
73 times that I had to write this to stop the repeat questions. |
|
74 <H2><A NAME="s2">2. Installation</A></H2> |
|
75 |
|
76 <H2>2.1 Get the files</H2> |
|
77 |
|
78 <P>Visit the VMailMgr website |
|
79 <A HREF="http://www.vmailmgr.org/">http://www.vmailmgr.org/</A> to |
|
80 get the package. |
|
81 <P>If you get the binary RPMS you will need at least the vmailmgr package. |
|
82 <H2>2.2 Install with RPMS</H2> |
|
83 |
|
84 <H3>Compiling SRC.RPM's</H3> |
|
85 |
|
86 <P>Simply compile the src.rpm file with the `<CODE>rpm --rebuild</CODE>` command. |
|
87 -Example- |
|
88 <HR> |
|
89 <PRE> |
|
90 rpm -ivh vmailmgr-0.96.9-1.src.rpm |
|
91 </PRE> |
|
92 <HR> |
|
93 <H3>Installing RPM's</H3> |
|
94 |
|
95 <P>After compiling the source rpms, the binaries will be located |
|
96 in `<CODE>/usr/src/redhat/RPMS/i386/</CODE>` or something similar. |
|
97 <P>Simply run the following command for each package |
|
98 <PRE> |
|
99 rpm -ivh <location>/<package.i386.rpm> |
|
100 </PRE> |
|
101 |
|
102 -Example- |
|
103 <HR> |
|
104 <PRE> |
|
105 rpm -ivh /usr/src/redhat/RPMS/i386/vmailmgr-0.96.9-1.i386.rpm |
|
106 rpm -ivh /usr/src/redhat/RPMS/i386/vmailmgr-daemon-0.96.9-1.i386.rpm |
|
107 </PRE> |
|
108 <HR> |
|
109 <P> |
|
110 <P> |
|
111 <H2>2.3 Install with source</H2> |
|
112 |
|
113 <P>If you dont ue RPMS you can install from source. |
|
114 <P>Run the following command |
|
115 <PRE> |
|
116 (As non-root user) |
|
117 tar zxf <package.tar.gz> |
|
118 cd <newly created dir> |
|
119 ./configure |
|
120 make |
|
121 (As root) |
|
122 make install |
|
123 </PRE> |
|
124 |
|
125 -Example- |
|
126 <HR> |
|
127 <PRE> |
|
128 (As non-root user) |
|
129 tar zxf vmailmgr-0.96.9.tar.gz |
|
130 cd vmailmgr-0.96.9 |
|
131 ./configure |
|
132 make |
|
133 (As root) |
|
134 make install |
|
135 </PRE> |
|
136 <HR> |
|
137 |
|
138 That should do it. |
|
139 <H2><A NAME="s3">3. Setup</A></H2> |
|
140 |
|
141 <P>In the following setup examples, it is assumed that your binaries |
|
142 are installed in `<CODE>/usr/bin</CODE>`, and configuration is in |
|
143 `<CODE>/etc/vmailmgr</CODE>`, as is the case if you installed from the |
|
144 RPMs. |
|
145 If you installed from source, configure puts the binaries into |
|
146 `<CODE>/usr/local/bin</CODE>` and the configuration into |
|
147 `<CODE>/usr/local/etc/vmailmgr</CODE>` by default. |
|
148 <H2>3.1 Setting Up a Virtual Domain</H2> |
|
149 |
|
150 <P>The following steps are necessary to set up a virtual domain with |
|
151 vmailmgr (assuming vmailmgr has been compiled and installed). As an |
|
152 example, we'll set up a virtual user `<CODE>me@mydomain.org</CODE>`, |
|
153 with aliases of `<CODE>myself@mydomain.org</CODE>` and |
|
154 `<CODE>myname@mydomain.org</CODE>`. |
|
155 <OL> |
|
156 <LI>Set up a DNS entry for the domain. This is not covered here, as it |
|
157 is dependant on far too many other things. I will mention that to |
|
158 make IP based virtual domains work a PTR record which matches an |
|
159 entry in virtualdomains is nessesary, for example, if nslookup |
|
160 10.56.33.122 returns <CODE>mail.mydomain.com</CODE>, |
|
161 `<CODE>virtualdomains</CODE>` needs an entry like |
|
162 `<CODE>mail.mydomain.com:myuser</CODE>' |
|
163 For the example, we'll assume that the mail exchanger for |
|
164 mydomain.org is already set up to point to your computer.</LI> |
|
165 <LI>Set up a base user for the domain. Create a user, with a name of |
|
166 your choosing. Since the maildirs for all the users in the |
|
167 virtual domain will be stored under this user's home directory, |
|
168 make sure you set the user up in a partition or disk that is |
|
169 appropriate for such storage. The tools that you should use to |
|
170 accomplish this step vary greatly between different systems. For |
|
171 our example, I'll add a user `<CODE>myuser</CODE>`.</LI> |
|
172 <LI>Configure qmail to recognize the domain. To do this, you need to |
|
173 modify two of qmail's configuration files in |
|
174 `<CODE>/var/qmail/control</CODE>` `<CODE>rcpthosts</CODE>` and |
|
175 `<CODE>virtualdomains</CODE>`. |
|
176 <UL> |
|
177 <LI>To `<CODE>rcpthosts</CODE>` : |
|
178 add the line `<CODE>mydomain.org</CODE>`. </LI> |
|
179 <LI>To `<CODE>virtualdomains</CODE>` : |
|
180 add the line `<CODE>mydomain.org:myuser</CODE>`.</LI> |
|
181 </UL> |
|
182 |
|
183 If you wish to have mail to `<CODE>anything.mydomain.org</CODE>` |
|
184 be delivered in the same way, add the following |
|
185 <UL> |
|
186 <LI>To `<CODE>rcpthosts</CODE>` : |
|
187 add the line `<CODE>.mydomain.org</CODE>`. </LI> |
|
188 <LI>To `<CODE>virtualdomains</CODE>` : |
|
189 add the line `<CODE>.mydomain.org:myuser</CODE>`.</LI> |
|
190 </UL> |
|
191 </LI> |
|
192 <LI>Configure qmail-popup/qmail-pop3d to use `<CODE>checkvpw</CODE>` as |
|
193 the password checker. This step is dependant on how you have |
|
194 installed qmail. |
|
195 <UL> |
|
196 <LI>Replace `<CODE>checkpassword</CODE>` in the command you use to |
|
197 invoke qmail-popup/qmail-pop3d (either in |
|
198 `<CODE>/etc/inet.conf</CODE>` or in a `<CODE>tcpserver</CODE>` |
|
199 command) with `<CODE>checkvpw</CODE>`.</LI> |
|
200 <LI>And/Or at the prompt type: `<CODE>echo checkvpw > |
|
201 /var/qmail/control/checkpassword</CODE>`</LI> |
|
202 </UL> |
|
203 </LI> |
|
204 <LI>Set up the vmailmgr files: |
|
205 <UL> |
|
206 <LI>Either change user to the user you just created (for example, |
|
207 type `<CODE>su - myuser</CODE>`) or log in (with either telnet or |
|
208 at the console) as the new user.</LI> |
|
209 <LI>Set up the base vmailmgr files by running `<CODE>vsetup</CODE>`.</LI> |
|
210 <LI>Use the included programs to add users and aliases. |
|
211 For our example, we would type the following commands: |
|
212 <PRE> |
|
213 vadduser me |
|
214 vaddalias myself me |
|
215 vaddalias myname me |
|
216 </PRE> |
|
217 </LI> |
|
218 </UL> |
|
219 </LI> |
|
220 </OL> |
|
221 |
|
222 After you have completed all these steps, you will need to kill and |
|
223 restart `<CODE>qmail-send</CODE>` to make it read the new |
|
224 `<CODE>virtualdomains</CODE>` table. |
|
225 <P>If you are using `<CODE>inetd</CODE>` to launch `<CODE>qmail-popup</CODE>`, |
|
226 `<CODE>kill -HUP</CODE>` the `<CODE>inetd</CODE>` process as well. |
|
227 <H2>3.2 Using one IP address for mutiple domains</H2> |
|
228 |
|
229 <P>There are two ways to log in without using multiple IP addresses. |
|
230 <P> |
|
231 <OL> |
|
232 <LI>The first way is to log in as |
|
233 `<CODE>userSEPvirtual.domain.org</CODE>`, where `<CODE>user</CODE>` is the |
|
234 mailbox name of the virtual user, SEP is one of `<CODE>@</CODE>` or |
|
235 `<CODE>:</CODE>` (by default, this is configurable in the |
|
236 `<CODE>/etc/vmailmgr/</CODE>' directory), and |
|
237 `<CODE>virtual.domain.org</CODE>' is the virtual domain's name, as |
|
238 listed in `<CODE>/var/qmail/control/virtualdomains</CODE>'.</LI> |
|
239 <LI>The second way is to use the internal form of the mailbox name -- |
|
240 that is, `<CODE>baseuser-user</CODE>', where `<CODE>user</CODE>' is the |
|
241 same as above, and `<CODE>baseuser</CODE>' is the username of the |
|
242 managing user.</LI> |
|
243 </OL> |
|
244 |
|
245 Example: `<CODE>/var/qmail/control/virtualdomains</CODE>' contains |
|
246 <PRE> |
|
247 testdomain.org:testuser |
|
248 </PRE> |
|
249 |
|
250 User `<CODE>myuser</CODE>' exists, and has set up a virtual mailbox with |
|
251 the name `<CODE>me</CODE>'. The `<CODE>separators</CODE>' variable in |
|
252 `<CODE>/etc/vmailmgr/</CODE>' contains `<CODE>@:</CODE>'. This virtual user |
|
253 could log in as `<CODE>me@mydomain.com</CODE>', |
|
254 `<CODE>me:mydomain.cm</CODE>', or `<CODE>myuser-me</CODE>'. |
|
255 <P> |
|
256 <P> |
|
257 <H2>3.3 Catching all misdirected mail in a virtual domain</H2> |
|
258 |
|
259 <P>In the `<CODE>vmailmgr/</CODE>' configuration directory, there is an |
|
260 entry called `<CODE>default-username</CODE>'. If mail to a virtual |
|
261 domain does not match any users or aliases in that domain, it is |
|
262 delivered to the name listed in this configuration item if it exists |
|
263 (which defaults to `<CODE>+</CODE>'). To make this deliver to you, |
|
264 simply type: |
|
265 <PRE> |
|
266 vaddalias + me |
|
267 </PRE> |
|
268 <H2>3.4 VMailMgr IMAP support</H2> |
|
269 |
|
270 <P>VMailMgr supports Courier-IMAP, but Courier-IMAP does not come with |
|
271 an authentication module for VMailMgr. This means that some minor |
|
272 work is required for making the two work together. |
|
273 <UL> |
|
274 <LI>You must copy `<CODE>/usr/bin/authvmailmgr</CODE>` to |
|
275 `<CODE>/usr/lib/courier-imap/libexec/authlib/authvmailmgr</CODE>`.</LI> |
|
276 <LI>Then modify the `<CODE>AUTHMODULES</CODE>` statement in |
|
277 `<CODE>/usr/lib/courier-imap/etc/imapd.config</CODE>` and add |
|
278 `<CODE>authvmailmgr</CODE>` as the first authentication module.</LI> |
|
279 </UL> |
|
280 <H2>3.5 Enabling enforcement of virtual user quotas</H2> |
|
281 |
|
282 <P>VMailMgr supports per-virtual-user quotas, but not out of the box, |
|
283 as it is not needed by the majority of users, and requires an extra |
|
284 program to be run on each delivery. |
|
285 To configure quota support, create the file |
|
286 `<CODE>/etc/vmailmgr/vdeliver-predeliver</CODE>`, containing |
|
287 the following: |
|
288 <PRE> |
|
289 #!/bin/sh |
|
290 /usr/bin/vcheckquota |
|
291 </PRE> |
|
292 |
|
293 This is executed as a shell script, so you will need to make it |
|
294 executable by running the following command: |
|
295 <PRE> |
|
296 chmod +x /etc/vmailmgr/vdeliver-predeliver |
|
297 </PRE> |
|
298 <H2>3.6 Enabling processing of autoresponses</H2> |
|
299 |
|
300 <P>Download and install the qmail-autoresponder package, found at |
|
301 <A HREF="http://em.ca/~bruceg/qmail-autoresponder/">http://em.ca/~bruceg/qmail-autoresponder/</A>. |
|
302 As with the above section, create a shell script |
|
303 `<CODE>/etc/vmailmgr/vdeliver-postdeliver</CODE>`, containing the |
|
304 following: |
|
305 <PRE> |
|
306 #!/bin/sh |
|
307 if test -s $MAILDIR/autoresponse/message.txt |
|
308 then |
|
309 qmail-autoresponder $MAILDIR/autoresponse/message.txt $MAILDIR/autoresponse |
|
310 fi |
|
311 </PRE> |
|
312 <H2>3.7 Web-based interfaces for vmailmgr</H2> |
|
313 |
|
314 <P>There are currently a few working solutions to administrate |
|
315 your vmailmgr system via a web interface. Only requirement is |
|
316 that the vmailmgrd daemon is running, and that you have |
|
317 a webserver on your system. |
|
318 <OL> |
|
319 <LI>For Python fans, there is vpyadmin by Bruce Guenter. The files can |
|
320 be downloaded at |
|
321 <A HREF="http://em.ca/~bruceg/vpyadmin/">http://em.ca/~bruceg/vpyadmin/</A>, and |
|
322 the development code is online at |
|
323 <A HREF="http://bruce-guenter.dyndns.org/cgi-bin/vpyadmin/">http://bruce-guenter.dyndns.org/cgi-bin/vpyadmin/</A> |
|
324 (sample.org / samplevm).</LI> |
|
325 <LI>And if you like PHP, you can use oMail-admin by Olivier Müller: |
|
326 it fully supports all vmailmgr functions, and speaks englich, |
|
327 french, italian, spanish, german and russian. Project homepage: |
|
328 <A HREF="http://omail.omnis.ch">http://omail.omnis.ch</A>. Online demo: |
|
329 <A HREF="http://admin.omnis.ch/omail/">http://admin.omnis.ch/omail/</A> (test.com / test).</LI> |
|
330 <LI>And there are also C-based CGI scripts in the <CODE>cgi</CODE> |
|
331 directory of the vmailmgr distribution.</LI> |
|
332 </OL> |
|
333 </BODY> |
|
334 </HTML> |