|
1 <!doctype linuxdoc system> |
|
2 |
|
3 <!-- LinuxDoc file was created by hand by <Dan Kuykendall> Wed April 23 --> |
|
4 <article> |
|
5 <title> |
|
6 VMailMgr FAQ |
|
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.0, 23 April 2000 |
|
14 </date> |
|
15 <abstract> |
|
16 VMailMgr Frequently Asked Questions. |
|
17 </abstract> |
|
18 |
|
19 <toc> |
|
20 |
|
21 <sect>Building and Installing |
|
22 |
|
23 <sect1>What compiler and libraries do I need to build vmailmgr? |
|
24 <p> |
|
25 You will need a working C and C++ compiler and linker. You will not |
|
26 need any C++ libraries. The package is being developed under Linux |
|
27 using egcs and glibc version 2, and may rely on some gcc/g++ |
|
28 extensions. |
|
29 </p> |
|
30 |
|
31 <sect1>Does vmailmgr work with shadow passwords? |
|
32 <p> |
|
33 This package should work without changes both with and without |
|
34 shadow passwords as long as the shadow password libraries are |
|
35 present when this package is built. The `configure' script will |
|
36 detect what method of shadow passwords are being used and the |
|
37 programs will be built accordingly. |
|
38 </p> |
|
39 |
|
40 <sect1>Does vmailmgr support IMAP? |
|
41 <p> |
|
42 Yes, vmailmgr supports Courier-IMAP. Some minor steps are needed to |
|
43 make them work, the steps are in the next section of this file. |
|
44 </p> |
|
45 |
|
46 <sect>Setup and Configuration |
|
47 |
|
48 <sect1>What other software is needed to run vmailmgr? |
|
49 <p> |
|
50 VMailMgr is based around qmail's handling of virtual users, and as |
|
51 such requires qmail for its operation. If you wish to use the `init' |
|
52 file to start/stop vmailmgrd or are installing the RPM package, |
|
53 supervise-scripts version 2.2 (or later, available at <url |
|
54 url="http://em.ca/~bruceg/supervise-scripts/">) and daemontools 0.60 |
|
55 (or later, available at <url |
|
56 url="http://em.ca/~bruceg/rpms/daemontools/">) packages are |
|
57 required. If you need to use the <tt>vmailmgrd</tt> daemon, you |
|
58 will also need the <tt>unixserver</tt> program, from the ucspi-unix |
|
59 package, available at <url url="http://em.ca/~bruceg/ucspi-unix/">. |
|
60 </p> |
|
61 |
|
62 <p> |
|
63 If you want to use the autoresponse feature, I recommend the use of |
|
64 my own autoresponder program, <tt>qmail-autoresponder</tt> available |
|
65 at <url url="http://em.ca/~bruceg/qmail-autoresponder/">. |
|
66 </p> |
|
67 |
|
68 <sect1>How do I record the output of vmailmgrd with syslog? |
|
69 <p> |
|
70 Output from vmailmgrd can be recorded by either splogger (part of |
|
71 qmail) or with the logger that comes with several flavours of |
|
72 UNIX. To use splogger, pipe the output of vmailmgrd into the command |
|
73 `splogger vmailmgrd'. This will timestamp each entry and tag them |
|
74 with the word `vmailmgrd'. By default, splogger logs to facility 2 |
|
75 (mail). To use logger, pipe the output of vmailmgrd into the |
|
76 comamand `<tt>logger -t vmailmgrd -p mail.notice</tt>'. See the |
|
77 respective man pages of these two programs for more information. |
|
78 </p> |
|
79 <p> |
|
80 Note: The use of syslog for logging messages is strongly discouraged |
|
81 due to problems with inefficent and buggy implementation of syslog. |
|
82 </p> |
|
83 |
|
84 <sect1>How do I record the output of vmailmgrd with multilog? |
|
85 <p> |
|
86 Make a directory into which the output will go, for example |
|
87 `<tt>/var/log/vmailmgrd</tt>'. Pipe the output of vmailmgrd into the |
|
88 command `<tt>multilog t /var/log/vmailmgrd</tt>'. See the |
|
89 documentation for multilog for more information on how to adjust its |
|
90 output. |
|
91 </p> |
|
92 |
|
93 <sect1>How do I setup VMmailMgr IMAP support? |
|
94 <p> |
|
95 VMailMgr supports Courier-IMAP, but Courier-IMAP does not auto |
|
96 detect VMailMgr. This means that some minor work is required for |
|
97 making the two work together. |
|
98 <itemize> |
|
99 <item>You must copy `<tt>/usr/local/bin/authvmailmgr</tt>` to |
|
100 `<tt>/usr/lib/courier-imap/libexec/authlib/authvmailmgr</tt>`. |
|
101 <item>Then modify the `<tt>AUTHMODULES</tt>` statement in |
|
102 `<tt>/usr/lib/courier-imap/etc/imapd.config</tt>` and add |
|
103 `<tt>authvmailmgr</tt>` as the first authentication module. |
|
104 </itemize> |
|
105 </p> |
|
106 |
|
107 <sect1>Upgrading from Previous Versions |
|
108 <p> |
|
109 If you are upgrading from an older version, you may need to make |
|
110 some changes to your system before or after doing the upgrade. The |
|
111 following table outlines the necessary changes. Note that you need |
|
112 to follow the instructions for all later versions of the software. |
|
113 <p> |
|
114 If you are upgrading from version: |
|
115 <descrip> |
|
116 <tag>0.96.6 or earlier</tag> |
|
117 <p> |
|
118 The `vmailmgrd' daemon needs to be run by unixserver, as opposed |
|
119 to being a stand-alone program previously. |
|
120 </p> |
|
121 <tag>0.96.2 or earlier</tag> |
|
122 <p> |
|
123 Make sure the `vmailmgrd' daemon and vmailmgr CGIs are disabled |
|
124 before upgrading, and upgrade them along with the main |
|
125 package. Changes were made to the daemon interface that will |
|
126 cause adding users and aliases to flake out. As well, the |
|
127 listdomain interface was completely redone. |
|
128 <p> |
|
129 <tag>0.94 or earlier, using the POP bulletin facility</tag> |
|
130 <p> |
|
131 The POP bulletin facility has been moved into a stand-alone |
|
132 program that needs to be executed through `checkvpw-postsetuid'. |
|
133 <p> |
|
134 <tag>0.93 or earlier</tag> |
|
135 <p> |
|
136 If you do not use the CGIs, you no longer need to run the |
|
137 `vmailmgrd' daemon. |
|
138 <p> |
|
139 <tag>0.92.2 or earlier</tag> |
|
140 <p> |
|
141 The configuration changed from reading a single file to reading a |
|
142 set of files in a directory. Read the configuration documentation |
|
143 and run the program `vconf2dir'. |
|
144 <p> |
|
145 <tag>0.90.2 or earlier</tag> |
|
146 <p> |
|
147 The name of the user to which mail to an unknown user is |
|
148 delivered changed from `*' to `+'. If you were using this |
|
149 feature, either change all your domains to accomodate this |
|
150 change, or set the `default-username' config file to contain `*'. |
|
151 <p> |
|
152 <tag>0.88 or earlier</tag> |
|
153 <p> |
|
154 The file format of the virtual password tables has changed from |
|
155 plain text files to CDB tables. You will need to suspend local |
|
156 deliveries before upgrading, and run the program `vpasswd2cdb' as |
|
157 each base user after upgrading, before re-enabling local |
|
158 deliveries. |
|
159 </descrip> |
|
160 </p> |
|
161 |
|
162 <sect1>How do I configure qmail+patches to use vmailmgr for POP? |
|
163 <p> |
|
164 Put the string `<tt>checkvpw</tt>' into the file |
|
165 `<tt>/etc/qmail/control/checkpassword</tt>' and restart pop3d by |
|
166 typing `<tt>/etc/rc.d/init.d/pop3d restart</tt>'. |
|
167 </p> |
|
168 |
|
169 <sect1>How do I allow clients to relay SMTP through me? |
|
170 <p> |
|
171 Download and install relay-ctrl from <url |
|
172 url="http://em.ca/~bruceg/relay-ctrl/">. |
|
173 It works with vmailmgr, for both POP3 and IMAP clients. |
|
174 </p> |
|
175 |
|
176 <sect>Usage |
|
177 |
|
178 <sect1>I can only use one IP address. How do I log in as a virtual user? |
|
179 <p> |
|
180 There are two ways to log in without using multiple IP addresses. |
|
181 <p> |
|
182 The first way is to log in as `userSEPvirtual.domain.org', where |
|
183 `user' is the mailbox name of the virtual user, SEP is one of `@' or |
|
184 `:' (by default, this is configurable in the |
|
185 `<tt>/etc/vmailmgr/</tt>' directory), and |
|
186 `<tt>virtual.domain.org</tt>' is the virtual domain's name, as |
|
187 listed in `<tt>/var/qmail/control/virtualdomains</tt>'. |
|
188 <p> |
|
189 The second way is to use the internal form of the mailbox name -- |
|
190 that is, `<tt>baseuser-user</tt>', where `<tt>user</tt>' is the same |
|
191 as above, and `<tt>baseuser</tt>' is the username of the managing |
|
192 user. |
|
193 |
|
194 Example: `<tt>/var/qmail/control/virtualdomains</tt>' contains |
|
195 <verb> |
|
196 testdomain.org:testuser |
|
197 </verb> |
|
198 User `<tt>testuser</tt>' exists, and has set up a virtual mailbox |
|
199 with the name `<tt>v</tt>'. The `<tt>separators</tt>' variable in |
|
200 `<tt>/etc/vmailmgr/</tt>' contains `<tt>@:</tt>'. This virtual user |
|
201 could log in as `<tt>v@testdomain.org</tt>', |
|
202 `<tt>v:testdomain.org</tt>', or `<tt>testuser-v</tt>'. |
|
203 <p> |
|
204 |
|
205 <sect1>How do I get all misdirected mail sent to me? |
|
206 <p> |
|
207 In the `<tt>vmailmgr/</tt>' configuration directory, there is an |
|
208 entry called `<tt>default-username</tt>'. If mail to a virtual |
|
209 domain does not match any users or aliases in that domain, it is |
|
210 delivered to the name listed in this configuration item if it exists |
|
211 (which defaults to `<tt>+</tt>'). To make this deliver to you, |
|
212 simply type: |
|
213 <verb> |
|
214 vaddalias + me |
|
215 </verb> |
|
216 </p> |
|
217 |
|
218 <sect>Troubleshooting |
|
219 |
|
220 <sect1>Bind error message from vmailmgrd. |
|
221 <p> |
|
222 If vmailmgrd reports `<tt>vmailmgrd: bind: no such file or |
|
223 directory</tt>' when you start it up, it means that can't create its |
|
224 socket file. By default, it will try to create the socket file |
|
225 `<tt>/tmp/.vmailmgrd</tt>'. You must ensure that `<tt>/tmp</tt>' is |
|
226 writable, or that the socket is created in some other place by |
|
227 setting `<tt>socket-file</tt>' in the configuration. |
|
228 </p> |
|
229 |
|
230 <sect1>Error sending to an alias: qmail-queue exited with an error! |
|
231 <p> |
|
232 If qmail reports "deferral: vdeliver: qmail-queue exited with an |
|
233 error!", check where your qmail is installed. On Debian systems, |
|
234 you will need to type "<tt>ls -s /usr/sbin /var/qmail/bin</tt>", |
|
235 since they've installed the qmail binaries into /usr/sbin. |
|
236 </p> |
|
237 |
|
238 <sect1>Running vmailmgrd fails. |
|
239 <p> |
|
240 When run by itself, vmailmgrd will report "<tt>Timed out waiting for |
|
241 remote</tt>". vmailmgrd needs to be run from unixserver, part of |
|
242 the ucspi-unix package available at <url |
|
243 url="http://em.ca/~bruceg/ucspi-unix/">. |
|
244 </p> |
|
245 |
|
246 <sect1>POP3 or IMAP logins take 30 seconds or longer. |
|
247 <p> |
|
248 This is almost certainly a DNS lookup problem. Make sure that DNS |
|
249 lookups aren't timing out, that lookups on all your IP addresses |
|
250 aren't failing, and that you can lookup remote addresses as well. |
|
251 </p> |
|
252 |
|
253 <p> |
|
254 If you are using 'tcpserver' for the head end to qmail-pop3d, then you |
|
255 may want to the following 2 switches to the command line: <tt>-R</tt> |
|
256 and <tt>-H</tt>. The former prevents tcpserver from attempting to |
|
257 obtain TCPREMOTEINFO from the remote host. This eliminates an "ident" |
|
258 lookup that may be being blocked or silently dropped by a firewall. |
|
259 The latter prevents tcpserver from doing a DNS lookup on the remote |
|
260 IP. |
|
261 </p> |
|
262 |
|
263 <sect>Miscellaneous |
|
264 |
|
265 <sect1>How do I get in contact with other users? |
|
266 <p> |
|
267 There is a mailing list run by the author. To subscribe, send an |
|
268 e-mail (content and subject line is ignored) to <url |
|
269 url="mailto:vmailmgr-subscribe@lists.em.ca">. |
|
270 <p> |
|
271 Remember that if you have a problem that you want us to diagnose, we |
|
272 need to know the following important details: |
|
273 <enum> |
|
274 <item>The output of `<tt>qmail-showctl</tt>` |
|
275 <item>The contents of the vmailmgrd log for the attempt you are |
|
276 trying to diagnose |
|
277 <item>The contents of the qmail and smtpd logs for a failed delivery |
|
278 attempt |
|
279 <item>The contents of the pop3d logs for a failed login attempt |
|
280 <item>The complete command line with which vmailmgrd and qmail-pop3d |
|
281 was invoked |
|
282 </enum> |
|
283 Please do not contact the author directly with vmailmgr questions. |
|
284 </p> |
|
285 |
|
286 <sect1>Are development version of vmailmgr available anywhere? |
|
287 <p> |
|
288 Yes, they are available through anonymous CVS. |
|
289 To access the CVS server, set your <tt>CVSROOT</tt> to |
|
290 <tt>:pserver:cvs@bruce-guenter.dyndns.org:/CVS</tt>, log in with an |
|
291 empty password, and check out the <tt>vmailmgr</tt> module. |
|
292 </p> |
|
293 |
|
294 <sect1>How does incoming email get handled? |
|
295 <p> |
|
296 Incoming email is first received by the qmail SMTP daemon and |
|
297 inserted into the qmail queue. Then `<tt>qmail-send</tt>' examines |
|
298 the email envelope (which details the recipient address or |
|
299 addresses) to determine how to dispatch the message. It looks up the |
|
300 domain name of each recipient in |
|
301 `<tt>/var/qmail/control/virtualdomains</tt>', and prefixes the user |
|
302 name with the string that it finds. It then looks up the resulting |
|
303 user name in the system password table (or in |
|
304 `<tt>/var/qmail/users/cdb</tt>' if it exists) to find the base user |
|
305 name and home directory (which I will call `<tt>$HOME</tt>'). It |
|
306 then looks for the file `<tt>$HOME/.qmail-VIRTUAL</tt>'. If that's |
|
307 not found, it looks for the file `<tt>$HOME/.qmail-default</tt>', |
|
308 which will contain an instruction to pipe the message to |
|
309 `<tt>vdeliver</tt>'. |
|
310 <p> |
|
311 This is where vmailmgr first enters the picture. The virtual user |
|
312 name is sent to `vdeliver' through environment variables. It looks |
|
313 in the configuration files (in `<tt>$HOME/.vmailmgr</tt>' and then |
|
314 in `<tt>/etc/vmailmgr</tt>') to determine the location of the |
|
315 password table, and looks up the virtual user name in the table to |
|
316 determine delivery instructions. If the name is not found, the |
|
317 message is bounced and delivery ends. Otherwise, it then looks for |
|
318 the `<tt>vdeliver-predeliver</tt>' script in the configuration |
|
319 directories (in reverse order) and executes any that are found. It |
|
320 then delivers the message to all the listed destinations -- an |
|
321 optional mailbox directory and zero or more forwarding |
|
322 addresses. Finally, it looks for the `<tt>vdeliver-postdeliver</tt>' |
|
323 script and executes any that are found. |
|
324 </p> |
|
325 |
|
326 <sect1>How does outgoing email get handled? |
|
327 <p> |
|
328 Outgoing email is not handled by vmailmgr. For details on outgoing |
|
329 email handling, check the qmail documentation. |
|
330 </p> |
|
331 |
|
332 <sect1>What about security of CGI and PHP functions? |
|
333 <p> |
|
334 The socket used by the daemon is a UNIX-domain socket (as opposed to |
|
335 Internet-domain), meaning you need local access on the computer to |
|
336 open up a connection. The path for this socket is run-time |
|
337 configurable. |
|
338 </p> |
|
339 <p> |
|
340 The daemon forks a new connection for each connection, up to a |
|
341 configurable maximum (at which point it stops listening, IIRC, I |
|
342 should verify this). The idea of threading has been completely |
|
343 discarded to avoid a bug in a command creeping in and makeing the |
|
344 whole server break. |
|
345 </p> |
|
346 <p> |
|
347 The protocol spoken over the socket is explicitly bounded to at most |
|
348 64kB of data, and all data is prefixed by a size. Static-sized |
|
349 buffers are only used with static-sized reads, and therefore can't be |
|
350 overflowed with stack-smashing tricks. |
|
351 </p> |
|
352 <p> |
|
353 The daemon commands setuid to the appropriate user as soon as the base |
|
354 user has been verified, to avoid doing any more than necessary as |
|
355 root, as well as to avoid the possibility of tricking the daemon into |
|
356 reading a file another user wouldn't normally have access to. |
|
357 </p> |
|
358 <p> |
|
359 To help avoid DoS on the local computer, a 1-second alarm is set as |
|
360 soon as the connection is received, and is only cleared once all the |
|
361 data has been read. If it takes longer than 1 second to read the data |
|
362 from the socket, the server process exits. |
|
363 </p> |
|
364 |
|
365 <sect1>What are the differences between vmailmgr and vpopmail? |
|
366 <p> |
|
367 The primary difference between vmailmgr and vpopmail is the use of |
|
368 base users. With vmailmgr there is one base user for each virtual |
|
369 domain. With vpopmail, there is one base user for the entire |
|
370 virtual domain system. |
|
371 </p> |
|
372 |
|
373 </article> |