vmailmgr: comparison doc/FAQ.info

equal deleted inserted replaced

-:30113bfbe723
+:b3afb9f1e801
+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
+<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:
+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.