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