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