diff -r 30113bfbe723 -r b3afb9f1e801 doc/FAQ.info --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/FAQ.info Sun Jan 20 00:22:09 2008 +0100 @@ -0,0 +1,370 @@ +This is FAQ.info, produced by makeinfo version 4.7 from FAQ.texi. + + Copyright (C) 1998 Bruce Guenter + + VMailMgr Frequently Asked Questions. + +1 Building and Installing +************************* + +1.1 What compiler and libraries do I need to build vmailmgr? +============================================================ + +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. + +1.2 Does vmailmgr work with shadow passwords? +============================================= + +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. + +1.3 Does vmailmgr support IMAP? +=============================== + +Yes, vmailmgr supports Courier-IMAP. Some minor steps are needed to +make them work, the steps are in the next section of this file. + +2 Setup and Configuration +************************* + +2.1 What other software is needed to run vmailmgr? +================================================== + +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 +`http://untroubled.org/supervise-scripts/') and daemontools 0.60 (or +later, available at `http://untroubled.org/rpms/daemontools/') 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 +`http://untroubled.org/ucspi-unix/'. + + If you want to use the autoresponse feature, I recommend the use of +my own autoresponder program, `qmail-autoresponder' available at +`http://untroubled.org/qmail-autoresponder/'. + +2.2 How do I record the output of vmailmgrd with syslog? +======================================================== + +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 command +`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'. + +2.3 How do I record the output of vmailmgrd with multilog? +========================================================== + +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. + +2.4 How do I setup VMmailMgr IMAP support? +========================================== + +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. + + * You must copy `/usr/local/bin/authvmailmgr' to + `/usr/lib/courier-imap/libexec/authlib/authvmailmgr'. + + * Then modify the `AUTHMODULES' statement in + `/usr/lib/courier-imap/etc/imapd.config' and add `authvmailmgr' as + the first authentication module. + + +2.5 Upgrading from Previous Versions +==================================== + +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. + +2.5.1 Upgrading from version 0.96.6 or earlier +---------------------------------------------- + +The `vmailmgrd' daemon needs to be run by unixserver, as opposed to +being a stand-alone program previously. + +2.5.2 Upgrading from version 0.96.2 or earlier +---------------------------------------------- + +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. + +2.5.3 Upgrading from version 0.94 or earlier, using the POP bulletin facility +----------------------------------------------------------------------------- + +The POP bulletin facility has been moved into a stand-alone program +that needs to be executed through `checkvpw-postsetuid'. + +2.5.4 Upgrading from version 0.93 or earlier +-------------------------------------------- + +If you do not use the CGIs, you no longer need to run the `vmailmgrd' +daemon. + +2.5.5 Upgrading from version 0.92.2 or earlier +---------------------------------------------- + +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'. + +2.5.6 Upgrading from version 0.90.2 or earlier +---------------------------------------------- + +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 `*'. + +2.5.7 Upgrading from version 0.88 or earlier +-------------------------------------------- + +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. + +2.6 How do I configure qmail+patches to use vmailmgr for POP? +============================================================= + +Put the string `checkvpw' into the file +`/etc/qmail/control/checkpassword' and restart `qmail-pop3d' by typing +`/etc/rc.d/init.d/pop3d restart'. + +2.7 How do I allow clients to relay SMTP through me? +==================================================== + +Download and install relay-ctrl from +`http://untroubled.org/relay-ctrl/'. It works with vmailmgr, for both +POP3 and IMAP clients. + +3 Usage +******* + +3.1 I can only use one IP address. How do I log in as a virtual user? +===================================================================== + +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. + + For 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'. + +3.2 How do I get all misdirected mail sent to me? +================================================= + +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 + +3.3 How can I put system accounts in a virtual domain? +====================================================== + +System accounts are those listed in `/etc/password' (or +`/var/qmail/users/cdb'). The system accounts are accessable, either +though SMTP or POP3 or IMAP, as `name@DOMAIN', where DOMAIN is listed in +`/var/qmail/control/locals'. + + Virtual accounts exist only as an artifact of vmailmgr management. +They are accessable as `name@DOMAIN', where DOMAIN is listed in +`/var/qmail/control/virtualdomains'. + + You *cannot* mix accounts within a domain between system and +virtual domains. If the domain is in `control/locals', all accounts +for that domain must be system accounts. If it is in +`control/virtualdomains', all accounts for that domain must be virtual +accounts. Also, `control/locals' overrides `control/virtualdomains': +if the domain is in `locals', `virtualdomains' is ignored. + + As an aside, if the domain is neither in `locals' nor in +`virtualdomains', qmail will reject incoming messages, and vmailmgr will +treat it as local. + +4 Troubleshooting +***************** + +4.1 Bind error message from `vmailmgrd'. +======================================== + +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. + +4.2 Error sending to an alias: `qmail-queue' exited with an error! +================================================================== + +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'. + +4.3 Running `vmailmgrd' fails. +============================== + +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 `http://untroubled.org/ucspi-unix/'. + +4.4 POP3 or IMAP logins take 30 seconds or longer. +================================================== + +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 add 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. + +5 Miscellaneous +*************** + +5.1 How do I get in contact with other users? +============================================= + +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. + +5.2 Are development version of vmailmgr available anywhere? +=========================================================== + +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. + +5.3 How does incoming email get handled? +======================================== + +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. + +5.4 How does outgoing email get handled? +======================================== + +Outgoing email is not handled by vmailmgr. For details on outgoing +email handling, check the qmail documentation. + +5.5 What about security of CGI and PHP functions? +================================================= + +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 making 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. + +5.6 What are the differences between vmailmgr and vpopmail? +=========================================================== + +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. +