diff -r 30113bfbe723 -r b3afb9f1e801 doc/FAQ.texi --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/FAQ.texi Sun Jan 20 00:22:09 2008 +0100 @@ -0,0 +1,396 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename FAQ.info +@settitle Vmailmgr FAQ +@setchapternewpage off +@paragraphindent 5 +@footnotestyle end +@c %**end of header + +@ifinfo +Copyright @copyright{} 1998 Bruce Guenter +@end ifinfo + +@titlepage +@title Vmailmgr FAQ +@author Bruce Guenter +@author Dan Kuykendall +@subtitle @today{} +@end titlepage + +@ifinfo +VMailMgr Frequently Asked Questions. +@end ifinfo + +@c **************************************************************************** +@chapter Building and Installing + +@section 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. + +@section 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 @code{configure} script will +detect what method of shadow passwords are being used and the +programs will be built accordingly. + +@section 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. + +@c **************************************************************************** +@chapter Setup and Configuration + +@section 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 @code{init} +file to start/stop @code{vmailmgrd} or are installing the RPM package, +supervise-scripts version 2.2 (or later, available at +@uref{http://untroubled.org/supervise-scripts/}) +and daemontools 0.60 (or later, available at +@uref{http://untroubled.org/rpms/daemontools/}) +packages are required. If you need to use the @code{vmailmgrd} daemon, you +will also need the @code{unixserver} program, from the ucspi-unix package, +available at +@uref{http://untroubled.org/ucspi-unix/}. + +If you want to use the autoresponse feature, I recommend the use of +my own autoresponder program, @code{qmail-autoresponder} available +at +@uref{http://untroubled.org/qmail-autoresponder/}. + +@section How do I record the output of vmailmgrd with syslog? + +Output from @code{vmailmgrd} can be recorded by either @code{splogger} (part of +qmail) or with the logger that comes with several flavours of UNIX. To use +@code{splogger}, pipe the output of @code{vmailmgrd} into the command +@samp{splogger vmailmgrd}. This will timestamp each entry and tag them with the +word @samp{vmailmgrd}. By default, @code{splogger} logs to facility 2 (mail). To +use @code{logger}, pipe the output of @code{vmailmgrd} into the command +@samp{logger -t vmailmgrd -p mail.notice}. +See the respective man pages of these two programs for more information. + +Note: The use of @code{syslog} for logging messages is strongly discouraged +due to problems with inefficent and buggy implementation of @code{syslog}. + +@section How do I record the output of vmailmgrd with multilog? + +Make a directory into which the output will go, for example +@file{/var/log/vmailmgrd}. Pipe the output of @code{vmailmgrd} into the +command @samp{multilog t /var/log/vmailmgrd}. See the +documentation for @code{multilog} for more information on how to adjust its +output. + +@section 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. + +@itemize @bullet +@item +You must copy @file{/usr/local/bin/authvmailmgr} to +@file{/usr/lib/courier-imap/libexec/authlib/authvmailmgr}. + +@item +Then modify the @code{AUTHMODULES} statement in +@file{/usr/lib/courier-imap/etc/imapd.config} and add +@kbd{authvmailmgr} as the first authentication module. + +@end itemize + +@section 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. + +@subsection Upgrading from version 0.96.6 or earlier + +The @code{vmailmgrd} daemon needs to be run by unixserver, as opposed +to being a stand-alone program previously. + +@subsection Upgrading from version 0.96.2 or earlier + +Make sure the @code{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. + +@subsection 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 @code{checkvpw-postsetuid}. + +@subsection Upgrading from version 0.93 or earlier + +If you do not use the CGIs, you no longer need to run the +@code{vmailmgrd} daemon. + +@subsection 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 @code{vconf2dir}. + +@subsection Upgrading from version 0.90.2 or earlier + +The name of the user to which mail to an unknown user is +delivered changed from @samp{*} to @samp{+}. If you were using this +feature, either change all your domains to accomodate this +change, or set the @file{default-username} config file to contain @samp{*}. + +@subsection 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 @code{vpasswd2cdb} as +each base user after upgrading, before re-enabling local +deliveries. + +@section How do I configure qmail+patches to use vmailmgr for POP? + +Put the string @kbd{checkvpw} into the file +@file{/etc/qmail/control/checkpassword} and restart @code{qmail-pop3d} by +typing @samp{/etc/rc.d/init.d/pop3d restart}. + +@section How do I allow clients to relay SMTP through me? + +Download and install relay-ctrl from +@uref{http://untroubled.org/relay-ctrl/}. +It works with vmailmgr, for both POP3 and IMAP clients. + +@c **************************************************************************** +@chapter Usage + +@section 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. + +@itemize @bullet +@item +The first way is to log in as @samp{user@var{SEP}virtual.domain.org}, where +@samp{user} is the mailbox name of the virtual user, @var{SEP} is one of +@samp{@@} or @samp{:} (by default, this is configurable in the +@file{/etc/vmailmgr/} directory), and @samp{virtual.domain.org} is the virtual +domain's name, as listed in @file{/var/qmail/control/virtualdomains}. + +@item +The second way is to use the internal form of the mailbox name -- +that is, @samp{baseuser-user}, where @samp{user} is the same +as above, and @samp{baseuser} is the username of the managing +user. + +For example, @file{/var/qmail/control/virtualdomains} contains +@samp{testdomain.org:testuser}, user @samp{testuser} exists, +and has set up a virtual mailbox with the name @samp{v}. +The @var{separators} variable in @file{/etc/vmailmgr/} +contains @samp{@@:}. This virtual user +could log in as @samp{v@@testdomain.org}, +@samp{v:testdomain.org}, or @samp{testuser-v}. +@end itemize + +@section How do I get all misdirected mail sent to me? + +In the @file{vmailmgr/} configuration directory, there is an +entry called @file{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 @samp{+}). To make this deliver to you, +simply type: + +@example +vaddalias + me +@end example + +@section How can I put system accounts in a virtual domain? + +System accounts are those listed in @file{/etc/password} (or +@file{/var/qmail/users/cdb}). +The system accounts are accessable, either though SMTP or POP3 or IMAP, as +@samp{name@@@var{DOMAIN}}, where @var{DOMAIN} is listed in +@file{/var/qmail/control/locals}. + +Virtual accounts exist only as an artifact of vmailmgr management. +They are accessable as @samp{name@@@var{DOMAIN}}, where @var{DOMAIN} is listed +in @file{/var/qmail/control/virtualdomains}. + +You @strong{cannot} mix accounts within a domain between system and virtual +domains. If the domain is in @file{control/locals}, all accounts for that +domain must be system accounts. If it is in @file{control/virtualdomains}, all +accounts for that domain must be virtual accounts. Also, @file{control/locals} +overrides @file{control/virtualdomains}: if the domain is in @file{locals}, +@file{virtualdomains} is ignored. + +As an aside, if the domain is neither in @file{locals} nor in +@file{virtualdomains}, qmail will reject incoming messages, and vmailmgr will +treat it as local. + +@c **************************************************************************** +@chapter Troubleshooting + +@section Bind error message from @code{vmailmgrd}. + +If @code{vmailmgrd} reports +@quotation +vmailmgrd: bind: no such file or directory +@end quotation +when you start it up, it means that can't create its socket file. By default, +it will try to create the socket file @file{/tmp/.vmailmgrd}. You must ensure +that @file{/tmp/} is writable, or that the socket is created in some other place +by setting @var{socket-file} in the configuration. + +@section Error sending to an alias: @code{qmail-queue} exited with an error! + +If qmail reports +@quotation +deferral: vdeliver: qmail-queue exited with an error! +@end quotation +check where your qmail is installed. On Debian systems, +you will need to type @samp{ls -s /usr/sbin /var/qmail/bin}, +since they've installed the qmail binaries into @file{/usr/sbin}. + +@section Running @code{vmailmgrd} fails. + +When run by itself, @code{vmailmgrd} will report +@quotation +Timed out waiting for remote +@end quotation +@code{vmailmgrd} needs to be run from @code{unixserver}, part of the ucspi-unix +package available at +@uref{http://untroubled.org/ucspi-unix/}. + +@section 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 @code{tcpserver} for the head end to @code{qmail-pop3d}, then +you may want to add the following 2 switches to the command line: @samp{-R} and +@samp{-H}. The former prevents @code{tcpserver} from attempting to obtain +@var{TCPREMOTEINFO} from the remote host. This eliminates an @code{ident} +lookup that may be being blocked or silently dropped by a firewall. The latter +prevents @code{tcpserver} from doing a DNS lookup on the remote IP. + +@c **************************************************************************** +@chapter Miscellaneous + +@section 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 +@email{vmailmgr-subscribe@@lists.untroubled.org}. + +Remember that if you have a problem that you want us to diagnose, we +need to know the following important details: +@enumerate +@item +The output of @code{qmail-showctl} +@item +The contents of the @code{vmailmgrd} log for the attempt you are +trying to diagnose +@item +The contents of the qmail and smtpd logs for a failed delivery +attempt +@item +The contents of the pop3d logs for a failed login attempt +@item +The complete command line with which @code{vmailmgrd} and @code{qmail-pop3d} +was invoked +@end enumerate + +Please do not contact the author directly with vmailmgr questions. + +@section Are development version of vmailmgr available anywhere? + +Yes, they are available through anonymous CVS. +To access the CVS server, set your @code{CVSROOT} to +@kbd{:pserver:cvs@@bruce-guenter.dyndns.org:/CVS}, log in with an +empty password, and check out the @code{vmailmgr} module. + +@section How does incoming email get handled? + +Incoming email is first received by the qmail SMTP daemon and +inserted into the qmail queue. Then @code{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 +@file{/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 +@file{/var/qmail/users/cdb} if it exists) to find the base user +name and home directory (which I will call @code{$HOME}). It +then looks for the file @file{@code{$HOME}/.qmail-VIRTUAL}. If that's +not found, it looks for the file @file{@code{$HOME}/.qmail-default}, +which will contain an instruction to pipe the message to +@code{vdeliver}. + +This is where vmailmgr first enters the picture. The virtual user +name is sent to @code{vdeliver} through environment variables. It looks +in the configuration files (in @file{@code{$HOME}/.vmailmgr} and then +in @file{/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 @code{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 @code{vdeliver-postdeliver} +script and executes any that are found. + +@section How does outgoing email get handled? + +Outgoing email is not handled by vmailmgr. For details on outgoing +email handling, check the qmail documentation. + +@section 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. + +@section 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. + +@contents + +@bye +