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