diff -r 000000000000 -r 6f7a81934006 doc/FAQ.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/FAQ.txt Wed Jan 16 22:39:43 2008 +0100 @@ -0,0 +1,396 @@ + VMailMgr FAQ + Bruce Guenter , Dan Kuykendall + + v1.0, 23 April 2000 + + VMailMgr Frequently Asked Questions. + ______________________________________________________________________ + + Table of Contents + + + 1. Building and Installing + + 1.1 What compiler and libraries do I need to build vmailmgr? + 1.2 Does vmailmgr work with shadow passwords? + 1.3 Does vmailmgr support IMAP? + + 2. Setup and Configuration + + 2.1 What other software is needed to run vmailmgr? + 2.2 How do I record the output of vmailmgrd with syslog? + 2.3 How do I record the output of vmailmgrd with multilog? + 2.4 How do I setup VMmailMgr IMAP support? + 2.5 Upgrading from Previous Versions + 2.6 How do I configure qmail+patches to use vmailmgr for POP? + 2.7 How do I allow clients to relay SMTP through me? + + 3. Usage + + 3.1 I can only use one IP address. How do I log in as a virtual user? + 3.2 How do I get all misdirected mail sent to me? + + 4. Troubleshooting + + 4.1 Bind error message from vmailmgrd. + 4.2 Error sending to an alias: qmail-queue exited with an error! + 4.3 Running vmailmgrd fails. + 4.4 POP3 or IMAP logins take 30 seconds or longer. + + 5. Miscellaneous + + 5.1 How do I get in contact with other users? + 5.2 Are development version of vmailmgr available anywhere? + 5.3 How does incoming email get handled? + 5.4 How does outgoing email get handled? + 5.5 What about security of CGI and PHP functions? + 5.6 What are the differences between vmailmgr and vpopmail? + + + ______________________________________________________________________ + + 11.. BBuuiillddiinngg aanndd IInnssttaalllliinngg + + 11..11.. WWhhaatt ccoommppiilleerr aanndd lliibbrraarriieess ddoo II nneeeedd ttoo bbuuiilldd vvmmaaiillmmggrr?? + + You will need a working C and C++ compiler and linker. You will not + need any C++ libraries. The package is being developed under Linux + using egcs and glibc version 2, and may rely on some gcc/g++ + extensions. + + 11..22.. DDooeess vvmmaaiillmmggrr wwoorrkk wwiitthh sshhaaddooww ppaasssswwoorrddss?? + + This package should work without changes both with and without shadow + passwords as long as the shadow password libraries are present when + this package is built. The `configure' script will detect what method + of shadow passwords are being used and the programs will be built + accordingly. + + 11..33.. DDooeess vvmmaaiillmmggrr ssuuppppoorrtt IIMMAAPP?? + + Yes, vmailmgr supports Courier-IMAP. Some minor steps are needed to + make them work, the steps are in the next section of this file. + + 22.. SSeettuupp aanndd CCoonnffiigguurraattiioonn + + 22..11.. WWhhaatt ootthheerr ssooffttwwaarree iiss nneeeeddeedd ttoo rruunn vvmmaaiillmmggrr?? + + VMailMgr is based around qmail's handling of virtual users, and as + such requires qmail for its operation. If you wish to use the `init' + file to start/stop vmailmgrd or are installing the RPM package, + supervise-scripts version 2.2 (or later, available at + ) and daemontools 0.60 (or + later, available at ) + packages are required. If you need to use the vmailmgrd daemon, you + will also need the unixserver program, from the ucspi-unix package, + available at . + + If you want to use the autoresponse feature, I recommend the use of my + own autoresponder program, qmail-autoresponder available at + . + + 22..22.. HHooww ddoo II rreeccoorrdd tthhee oouuttppuutt ooff vvmmaaiillmmggrrdd wwiitthh ssyysslloogg?? + + Output from vmailmgrd can be recorded by either splogger (part of + qmail) or with the logger that comes with several flavours of UNIX. To + use splogger, pipe the output of vmailmgrd into the command `splogger + vmailmgrd'. This will timestamp each entry and tag them with the word + `vmailmgrd'. By default, splogger logs to facility 2 (mail). To use + logger, pipe the output of vmailmgrd into the comamand `logger -t + vmailmgrd -p mail.notice'. See the respective man pages of these two + programs for more information. + + Note: The use of syslog for logging messages is strongly discouraged + due to problems with inefficent and buggy implementation of syslog. + + 22..33.. HHooww ddoo II rreeccoorrdd tthhee oouuttppuutt ooff vvmmaaiillmmggrrdd wwiitthh mmuullttiilloogg?? + + Make a directory into which the output will go, for example + `/var/log/vmailmgrd'. Pipe the output of vmailmgrd into the command + `multilog t /var/log/vmailmgrd'. See the documentation for multilog + for more information on how to adjust its output. + + 22..44.. HHooww ddoo II sseettuupp VVMMmmaaiillMMggrr IIMMAAPP ssuuppppoorrtt?? + + VMailMgr supports Courier-IMAP, but Courier-IMAP does not auto detect + VMailMgr. This means that some minor work is required for making the + two work together. + + +o You must copy `/usr/local/bin/authvmailmgr` to `/usr/lib/courier- + imap/libexec/authlib/authvmailmgr`. + + +o Then modify the `AUTHMODULES` statement in `/usr/lib/courier- + imap/etc/imapd.config` and add `authvmailmgr` as the first + authentication module. + + 22..55.. UUppggrraaddiinngg ffrroomm PPrreevviioouuss VVeerrssiioonnss + + If you are upgrading from an older version, you may need to make some + changes to your system before or after doing the upgrade. The + following table outlines the necessary changes. Note that you need to + follow the instructions for all later versions of the software. + + If you are upgrading from version: + + 00..9966..66 oorr eeaarrlliieerr + The `vmailmgrd' daemon needs to be run by unixserver, as opposed + to being a stand-alone program previously. + + 00..9966..22 oorr eeaarrlliieerr + Make sure the `vmailmgrd' daemon and vmailmgr CGIs are disabled + before upgrading, and upgrade them along with the main package. + Changes were made to the daemon interface that will cause adding + users and aliases to flake out. As well, the listdomain + interface was completely redone. + + + 00..9944 oorr eeaarrlliieerr,, uussiinngg tthhee PPOOPP bbuulllleettiinn ffaacciilliittyy + The POP bulletin facility has been moved into a stand-alone + program that needs to be executed through `checkvpw-postsetuid'. + + + 00..9933 oorr eeaarrlliieerr + If you do not use the CGIs, you no longer need to run the + `vmailmgrd' daemon. + + + 00..9922..22 oorr eeaarrlliieerr + The configuration changed from reading a single file to reading + a set of files in a directory. Read the configuration + documentation and run the program `vconf2dir'. + + + 00..9900..22 oorr eeaarrlliieerr + The name of the user to which mail to an unknown user is + delivered changed from `*' to `+'. If you were using this + feature, either change all your domains to accomodate this + change, or set the `default-username' config file to contain + `*'. + + + 00..8888 oorr eeaarrlliieerr + The file format of the virtual password tables has changed from + plain text files to CDB tables. You will need to suspend local + deliveries before upgrading, and run the program `vpasswd2cdb' + as each base user after upgrading, before re-enabling local + deliveries. + + 22..66.. HHooww ddoo II ccoonnffiigguurree qqmmaaiill++ppaattcchheess ttoo uussee vvmmaaiillmmggrr ffoorr PPOOPP?? + + Put the string `checkvpw' into the file + `/etc/qmail/control/checkpassword' and restart pop3d by typing + `/etc/rc.d/init.d/pop3d restart'. + + 22..77.. HHooww ddoo II aallllooww cclliieennttss ttoo rreellaayy SSMMTTPP tthhrroouugghh mmee?? + + Download and install relay-ctrl from . It works with vmailmgr, for both POP3 and IMAP clients. + + 33.. UUssaaggee + + 33..11.. II ccaann oonnllyy uussee oonnee IIPP aaddddrreessss.. HHooww ddoo II lloogg iinn aass aa vviirrttuuaall + uusseerr?? + + There are two ways to log in without using multiple IP addresses. + + The first way is to log in as `userSEPvirtual.domain.org', where + `user' is the mailbox name of the virtual user, SEP is one of `@' or + `:' (by default, this is configurable in the `/etc/vmailmgr/' + directory), and `virtual.domain.org' is the virtual domain's name, as + listed in `/var/qmail/control/virtualdomains'. + + The second way is to use the internal form of the mailbox name -- that + is, `baseuser-user', where `user' is the same as above, and `baseuser' + is the username of the managing user. + + Example: `/var/qmail/control/virtualdomains' contains + + testdomain.org:testuser + + + User `testuser' exists, and has set up a virtual mailbox with the name + `v'. The `separators' variable in `/etc/vmailmgr/' contains `@:'. This + virtual user could log in as `v@testdomain.org', `v:testdomain.org', + or `testuser-v'. + + + + 33..22.. HHooww ddoo II ggeett aallll mmiissddiirreecctteedd mmaaiill sseenntt ttoo mmee?? + + In the `vmailmgr/' configuration directory, there is an entry called + `default-username'. If mail to a virtual domain does not match any + users or aliases in that domain, it is delivered to the name listed in + this configuration item if it exists (which defaults to `+'). To make + this deliver to you, simply type: + + vaddalias + me + + + + 44.. TTrroouubblleesshhoooottiinngg + + 44..11.. BBiinndd eerrrroorr mmeessssaaggee ffrroomm vvmmaaiillmmggrrdd.. + + If vmailmgrd reports `vmailmgrd: bind: no such file or directory' when + you start it up, it means that can't create its socket file. By + default, it will try to create the socket file `/tmp/.vmailmgrd'. You + must ensure that `/tmp' is writable, or that the socket is created in + some other place by setting `socket-file' in the configuration. + + 44..22.. EErrrroorr sseennddiinngg ttoo aann aalliiaass:: qqmmaaiill--qquueeuuee eexxiitteedd wwiitthh aann eerrrroorr!! + + If qmail reports "deferral: vdeliver: qmail-queue exited with an + error!", check where your qmail is installed. On Debian systems, you + will need to type "ls -s /usr/sbin /var/qmail/bin", since they've + installed the qmail binaries into /usr/sbin. + + 44..33.. RRuunnnniinngg vvmmaaiillmmggrrdd ffaaiillss.. + + When run by itself, vmailmgrd will report "Timed out waiting for + remote". vmailmgrd needs to be run from unixserver, part of the + ucspi-unix package available at . + + 44..44.. PPOOPP33 oorr IIMMAAPP llooggiinnss ttaakkee 3300 sseeccoonnddss oorr lloonnggeerr.. + + This is almost certainly a DNS lookup problem. Make sure that DNS + lookups aren't timing out, that lookups on all your IP addresses + aren't failing, and that you can lookup remote addresses as well. + + If you are using 'tcpserver' for the head end to qmail-pop3d, then you + may want to the following 2 switches to the command line: -R and -H. + The former prevents tcpserver from attempting to obtain TCPREMOTEINFO + from the remote host. This eliminates an "ident" lookup that may be + being blocked or silently dropped by a firewall. The latter prevents + tcpserver from doing a DNS lookup on the remote IP. + 55.. MMiisscceellllaanneeoouuss + + 55..11.. HHooww ddoo II ggeett iinn ccoonnttaacctt wwiitthh ootthheerr uusseerrss?? + + There is a mailing list run by the author. To subscribe, send an e- + mail (content and subject line is ignored) to . + + Remember that if you have a problem that you want us to diagnose, we + need to know the following important details: + + 1. The output of `qmail-showctl` + + 2. The contents of the vmailmgrd log for the attempt you are trying to + diagnose + + 3. The contents of the qmail and smtpd logs for a failed delivery + attempt + + 4. The contents of the pop3d logs for a failed login attempt + + 5. The complete command line with which vmailmgrd and qmail-pop3d was + invoked + + Please do not contact the author directly with vmailmgr questions. + + 55..22.. AArree ddeevveellooppmmeenntt vveerrssiioonn ooff vvmmaaiillmmggrr aavvaaiillaabbllee aannyywwhheerree?? + + Yes, they are available through anonymous CVS. To access the CVS + server, set your CVSROOT to :pserver:cvs@bruce- + guenter.dyndns.org:/CVS, log in with an empty password, and check out + the vmailmgr module. + + 55..33.. HHooww ddooeess iinnccoommiinngg eemmaaiill ggeett hhaannddlleedd?? + + Incoming email is first received by the qmail SMTP daemon and inserted + into the qmail queue. Then `qmail-send' examines the email envelope + (which details the recipient address or addresses) to determine how to + dispatch the message. It looks up the domain name of each recipient in + `/var/qmail/control/virtualdomains', and prefixes the user name with + the string that it finds. It then looks up the resulting user name in + the system password table (or in `/var/qmail/users/cdb' if it exists) + to find the base user name and home directory (which I will call + `$HOME'). It then looks for the file `$HOME/.qmail-VIRTUAL'. If that's + not found, it looks for the file `$HOME/.qmail-default', which will + contain an instruction to pipe the message to `vdeliver'. + + This is where vmailmgr first enters the picture. The virtual user name + is sent to `vdeliver' through environment variables. It looks in the + configuration files (in `$HOME/.vmailmgr' and then in `/etc/vmailmgr') + to determine the location of the password table, and looks up the + virtual user name in the table to determine delivery instructions. If + the name is not found, the message is bounced and delivery ends. + Otherwise, it then looks for the `vdeliver-predeliver' script in the + configuration directories (in reverse order) and executes any that are + found. It then delivers the message to all the listed destinations -- + an optional mailbox directory and zero or more forwarding addresses. + Finally, it looks for the `vdeliver-postdeliver' script and executes + any that are found. + + 55..44.. HHooww ddooeess oouuttggooiinngg eemmaaiill ggeett hhaannddlleedd?? + + Outgoing email is not handled by vmailmgr. For details on outgoing + email handling, check the qmail documentation. + + + 55..55.. WWhhaatt aabboouutt sseeccuurriittyy ooff CCGGII aanndd PPHHPP ffuunnccttiioonnss?? + + The socket used by the daemon is a UNIX-domain socket (as opposed to + Internet-domain), meaning you need local access on the computer to + open up a connection. The path for this socket is run-time + configurable. + + The daemon forks a new connection for each connection, up to a + configurable maximum (at which point it stops listening, IIRC, I + should verify this). The idea of threading has been completely + discarded to avoid a bug in a command creeping in and makeing the + whole server break. + + The protocol spoken over the socket is explicitly bounded to at most + 64kB of data, and all data is prefixed by a size. Static-sized + buffers are only used with static-sized reads, and therefore can't be + overflowed with stack-smashing tricks. + + The daemon commands setuid to the appropriate user as soon as the base + user has been verified, to avoid doing any more than necessary as + root, as well as to avoid the possibility of tricking the daemon into + reading a file another user wouldn't normally have access to. + + To help avoid DoS on the local computer, a 1-second alarm is set as + soon as the connection is received, and is only cleared once all the + data has been read. If it takes longer than 1 second to read the data + from the socket, the server process exits. + + 55..66.. WWhhaatt aarree tthhee ddiiffffeerreenncceess bbeettwweeeenn vvmmaaiillmmggrr aanndd vvppooppmmaaiill?? + + The primary difference between vmailmgr and vpopmail is the use of + base users. With vmailmgr there is one base user for each virtual + domain. With vpopmail, there is one base user for the entire virtual + domain system. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +