Running qmail under Gentoo Linux

Running qmail under Gentoo Linuxby Kris Kelley

NOTE:  This guide was written for use with qmail ebuild 1.03-r13.  The currentstable qmail ebuild is 1.03-r15.  Several other ebuilds mentioned in thisdocumentation also have been updated since the last revision.  Unfortunately,I do not expect to update this guide again any time soon, if ever.  I nolonger work as an email system administrator, I no longer have qmail running onany of my systems, and my time away from work is now devoted to other projects.The good news is that the Gentoo website now has Gentoo-specific documentationabout qmail and its related software packages.  I now recommend using theofficial documentation, as well as the Gentoo forums and the qmail mailinglist.

This guide will remain available at its original URL(http://www.skunkworx.org/guides/QmailOnGentoo.txt), for reference.  Also, foranybody who might wish to adapt and/or update this guide, I am making itavailable under the Creative Commons Attribution-ShareAlike 2.0 license;details are available at the license website(http://creativecommons.org/licenses/by-sa/2.0/).

I would like to thank everyone who provided constructive criticism and words ofencouragement while I was actively maintaining this guide.  I still believeqmail is the best email server program out there, for any platform, and I hopethe qmail and Gentoo communities continue to thrive.

Introduction

This document gives instructions on how to install, configure, and run qmail ona system running Gentoo Linux.  I originally wrote this after I could not findany qmail documentation specific to Gentoo, despite Gentoo offering packages(or "ebuilds", to use Gentoo's terminology) for qmail and related software.

You are probably not reading this if you are not familiar with Gentoo Linux,but just in case, Gentoo is a relatively new distribution that aims at strikinga compromise between the convenience and compatibility of a linux installationbased on ready-made software packages, and the power and configurability of alinux installation built from source.  For more details, visit Gentoo's website(http://www.gentoo.org).  Gentoo's promise of being able to tailor softwareexactly to a system's specifications, while at the same time having a packagemanager easily keep track of it all, is what attracted me to this distribution,to say nothing of the recommendations I received from friends and coworkers.

You are probably also not reading this if you have not heard of qmail, but tobe thorough, Daniel J. Bernstein's qmail is an email server software package,providing the same general functionality of packages like Sendmail or ssmtp.qmail is undebatably the most secure email server software available forUnix-compatible operating systems, and I would argue that it is the most secureemail server software period.  qmail also provides plenty of configurability,enough to suit the needs of almost any email-related task.  The fact that qmailhas not had an official release since 1997, and yet continues to grow inpopularity without a single security alert, is testimony of its quality.  qmailis not for the faint of heart, however.  Even with a versatile package managerlike Gentoo's Portage, qmail requires some manual intervention, not to mentionfirm knowledge of what you are doing, to run optimally.

Things to Know before Starting

These instructions were written using Gentoo Linux 1.4, installed followingthe distributors' instructions, and the qmail ebuild provided by Gentoothrough its package manager, Portage.  As of this writing, the recommendedGentoo ebuild for qmail is 1.03-r13.  There may be instructions here that arespecific to these versions; in particular, earlier versions of the qmailebuild are significantly different from 1.03-r13, and I do not recommendtrying to use this guide with them.  Also, Gentoo and Portage are highlycustomizable, and experienced Gentoo users who have heavily tweaked theirsystems may find these instructions completely off base.

The qmail ebuild is modeled on the process prescribed by "Life with qmail"(LWQ, http://www.lifewithqmail.org), written by Dave Sill.  LWQ is *required*reading; the instructions given here mostly highlight the differences betweenLWQ and the qmail ebuild, as well as the manual steps needed to completeqmail's installation and configuration.

Gentoo's qmail ebuild includes several patches to the original source code.These patches fix minor, non-critical bugs, and also provide additionalfeatures not present in the author's distribution of qmail 1.03, such as theability to encrypt SMTP sessions with SSL, and the ability to authenticatesessions with passwords unique to each user on your system.

(NOTE:  The current version of LWQ makes use of a package called netqmail.netqmail 1.05 is a patched version of qmail 1.03.  Bugs and incompatibilitiesfixed by netqmail 1.05 are also fixed by Gentoo's 1.03-r13 ebuild for qmail,and therefore LWQ is still an essential source of information, even for Gentoousers.)

IMPORTANT:  qmail, as well as any software package written in the Cprogramming language, relies on a package called glibc to provide the basicC function libraries.  As of this writing, Gentoo's recommended glibc ebuildis version 2.3.2-r9.  Because of an old coding method that is no longersupported by the authors of glibc, all qmail ebuilds older than 1.03-r10 (aswell as the unpatched source code for qmail 1.03) ARE NOT COMPATIBLE with anyebuilds based on glibc 2.3.2!  To ensure smooth installation, make sure youare using the latest unmasked ebuilds of qmail and all software packagesqmail depends on (including daemontools, ucspi-tcp, checkpassword,cmd5checkpw, dot-forward, and queue-fix; more information about these packagesis provided below.)

Part One - Configuring Gentoo to Allow qmail's Installation

Before you can install qmail, you may need to configure Gentoo to allow youto do so.  This requires knowing a few things about Gentoo and Portage.

One of Portage's features is the ability to keep track of "virtual" packages.Virtual packages are not specific software packages, but are definitionsthat can be matched by any Gentoo ebuild claiming to do so.  When you install(or "merge") an ebuild that matches the definition of a virtual package,Portage considers that virtual package present on your system.

Gentoo keeps a list of default ebuilds it will use to satisfy virtual packageneeds.  An ebuild from this list is merged whenever the associated virtualpackage is requested and a matching ebuild is not already present.  Many ofthese ebuilds are added to the system during Gentoo's initial set-up.

Much of Gentoo's behavior is governed by a set of configuration filescollectively known as a "profile."  Included in a profile is the default listfor satisfying virtual package requirements.  Regardless of what profile youuse, you can look at the associated files in /etc/make.profile.  Editingthese files is not a good idea, unless you are planning on building your ownprofiles for distribution.

Besides the default list supplied by a profile, Gentoo also keeps a list ofvirtual packages actually present on your system, and the ebuilds thatrepresent those virtual packages.  Gentoo keeps this list in the file/var/cache/edb/virtuals.  Whenever you merge an ebuild that satisfies therequirements for a virtual package, that virtual package's entry is createdor updated in /var/cache/edb/virtuals.

Gentoo ebuilds can be designed to block their own installation if they wouldconflict with other software already present on the system.  These blocks canbe based on virtual packages as well as specific ebuilds.

Gentoo controls the presence of an email server (or, more accurately, a "mailtransfer agent") with the virtual package "virtual/mta".  Gentoo's qmail ebuildis a virtual/mta package, but of course it is not the only one.  If youfollowed all instructions for installing Gentoo, ssmtp will be present on yoursystem, and will be listed in /var/cache/edb/virtuals.  Because most systemsreally only need one mail transfer agent, the ebuilds for ssmtp, qmail, andother MTAs will block installation if a virtual/mta package is already present.

So, if ssmtp or some other virtual/mta package is already installed on yoursystem, you will need to allow qmail to be installed on your system.  There aretwo good ways of doing this:

1.  Uninstall the virtual/mta package currently on your system.  Anyconfiguration you may have performed to run the current MTA on yoursystem, such as having it start automatically during system boot, willneed to be undone prior to removal.

2.  Edit the qmail ebuild script to remove the virtual/mta block.  Forversion 1.03-r13, the ebuild script is usually kept at/usr/portage/net-mail/qmail-1.03-r13.ebuild.  The edit involves findingthe two lines that look like this:

RDEPEND="!virtual/mtavirtual/glibc

and replacing them with this one line:

RDEPEND="virtual/glibc

#2 is the recommended choice, as other components of your system may complainabout the sudden lack of a virtual/mta package.  It is safe to keep yourcurrent MTA while installing and configuring qmail, as long as you do not tryto run both MTAs at the same time.

Once you have removed any currently installed virtual/mta packages, or havemodified the qmail ebuild script, you will be ready to install qmail.

IMPORTANT:  Before you can emerge qmail and related ebuilds, you must alsohave the right system users and groups on your system.  You will need usersnamed "alias", "qmaild", "qmaill", "qmailq", "qmailr", and "qmails", and groupsnamed "nofiles" and "qmail".  Also, the alias user's home directory must be setto /var/qmail/alias.  Normally this is all taken care of during Gentoo'sinstallation, specifically, when the baselayout package is emerged.  If youhave since edited your users and groups files, removing entries you believedwere unnecessary, make sure you have the right users and groups beforeproceeding!

Part Two - Installing and Configuring qmail and Related Software

Thanks to Portage and the "emerge" command, all of the software required forrunning qmail is installed with a single command.  However, keep in mind thatthe authors of Gentoo recommend you always run emerge with the "pretend" flagprior to installing any new packages, so that you know for certain what isabout to be installed on your system.

# emerge -p qmail

These are the packages that I would merge...

(NOTE:  The 1.03-r13 qmail ebuild uses one USE flag, "ssl".  You must set thisUSE flag, either in /etc/make.conf or in your shell's USE environmentvariable, if you want to install qmail with encrypted SMTP support.  Moreinformation about encrypted SMTP is in appendix B.5)

Depending on what you already have available, you will see a number ofebuilds that Portage would merge along with qmail.  Most likely you will see"ucspi-tcp", "daemontools", "dot-forward", "checkpassword", "cmd5checkpw", and"queue-fix" in this list.  Except for "cmd5checkpw" and "queue-fix", these areadditional tools written by Bernstein, designed to provide a stable, easilyconfigurable environment for qmail.  "ucspi-tcp" and "daemontools" inparticular are required packages for a qmail installation that conforms to LWQ,and Gentoo's default configuration appropriately defines qmail as dependent onthese packages.

(NOTE:  "cmd5checkpw" is used to offer authenticated SMTP; see appendix B.3 formore information.  "queue-fix" is used to initially create the qmail queue,that is, the folders qmail uses to temporarily store email that is beingprocessed; it can also be used to repair or recreate the queue when needed.)

Once you are satisfied in knowing what is going to be added to your system,run emerge again without the "pretend" flag.

# emerge qmail

When this command finishes, the system will be almost ready.  Portage not onlyinstalls qmail and all related software, but also performs a number ofnecessary system configurations, and installs several scripts documented in LWQ.

Gentoo's qmail ebuild includes an option that allows for some additionalautomatic configuration.  In fact, this extra configuration will be enough forqmail to run securely and effectively on many systems.  However, while Irecommend taking advantage of this option to prevent any security checkpointsfrom being accidentally overlooked, this feature should not be considered asubstitute for following the rest of this guide, especially if qmail is to beused in a production environment.  To perform the additional automaticconfiguration, run this command:

# ebuild /var/db/pkg/net-mail/qmail-1.03-r13/qmail-1.03-r13.ebuild config

If run, the above command will look up the machine's fully qualified domainname, and set up qmail to treat as local any email bound for this namespecifically.  For example, if the fully qualified domain name ismachine.example.com, qmail will process for local delivery any email bound foraddresses ending in "@machine.example.com" (but not "@example.com").  qmailwill also be set up to allow SMTP (mail transport) connections from anywhere.For local connections, all email will be accepted, and any email notdestined for local delivery will be directed (or "relayed") to the appropriatedestination.  For all other connections, only email destined for local deliverywill be accepted.  These configurations may not be exactly what you want, socontinue reading to learn how to configure qmail to suit your needs.

(NOTE:  Running the above ebuild command will also generate a self-signed SSLcertificate for use with encrypted SMTP.  See appendix B.5 for moreinformation.  If you plan on making use of encrypted SMTP, first edit/var/qmail/control/servercert.cnf, particularly the values in the "req_dn"section, before running the above ebuild command.  This will ensure your newSSL certificate contains the correct information for your system.  Rememberthat qmail needs to be emerged with the "ssl" USE flag for encrypted SMTP towork.)

From this point, follow LWQ starting with section 2.7.  Refer to theinstructions below for Gentoo-specific notes related to each section.

2.7.  daemontools has already been installed by Portage by this point,however, the daemontools ebuild does not change /etc/inittab.  Instead,the ebuild provides an rc script for svscan in /etc/init.d.  To ensurethat svscan will start during system boot, use Gentoo's rc-update commandto link the svscan rc script within the appropriate runlevel directoryor directories.  If you plan on running qmail from the default runlevel,enter this command:

rc-update add svscan default

Note that starting svscan from an rc script does not protect it fromunexpected termination.  If you would like to take advantage of init'sability to recreate processes that have died, do *not* use Gentoo's rcscript for svscan.  Instead, edit /etc/inittab, adding this line:

SV:12345:respawn:/usr/bin/svscanboot

Note that the ebuild uses a different directory for daemontools'executables than the author's original package.

2.8.1.  The qmail ebuild supplies a /var/qmail/rc script and a/var/qmail/control/defaultdelivery control file similar to the onesgiven in LWQ.  In the Gentoo ebuild versions, comments are allowed in/var/qmail/control/defaultdelivery; any line starting with "#" will beignored.

The ebuild configures qmail to use maildirs, however, note that the name ofeach user's maildir directory is slightly different than that given in LWQ(".maildir/" instead of "Maildir/").

2.8.2.1.  The qmail ebuild does not provide the /var/qmail/bin/qmailctlscript.  Instead, a script named qmail-control is created and placed in/var/qmail/bin.  qmail-control allows for qmail's services to be stoppedand started, and for the locals and virtualdomains control files (seebelow) to be reread.  qmailctl offers the same functionality and more,providing an easy, convenient alternative to remembering several differentcommands.  So, while creating /var/qmail/bin/qmailctl as documented in thissection of LWQ is not necessary, it is highly recommended.

The comments for Red Hat Linux's chkconfig tool are not needed.  PATHdoes not have to include /usr/local/bin or /usr/local/sbin; thesedirectories are empty on a typical Gentoo system.

2.8.2.2.  Gentoo's qmail ebuild creates all the necessary supervisescripts that are documented in this section of LWQ.

/var/qmail/supervise/qmail-send/log/run and/var/qmail/supervise/qmail-smtpd/log/run, as created by the qmail ebuild,are slightly different than those given by LWQ.  The difference enables themultilog program to rotate the log files of qmail-send and qmail-smtpd whenthey reach approximately 2.5MB in size, instead of the default 100kB.

(NOTE:  See http://cr.yp.to/daemontools/multilog.html for more informationabout how multilog maintains log files.)

/var/qmail/supervise/qmail-smtpd/run as provided by the ebuild is verydifferent from the one presented in LWQ.  Generally speaking, version1.03-r13 of the qmail ebuild was designed so that qmail's functionalitycould be changed entirely with configuration files, removing the need formanipulating any qmail-related scripts or programs.  In particular,the Gentoo version of /var/qmail/supervise/qmail-smtpd/run relies on theGentoo-specific control files /var/qmail/control/conf-common and/var/qmail/control/conf-smtpd for configuring qmail's SMTP service.Editing these files is not essential for basic qmail and SMTPfunctionality, and is also not recommended for those installing qmail forthe first time.  Once you are comfortable with how qmail operates, andwould like to take advantage of features like authenticated SMTP or spamblacklisting, you can edit these configuration files to suit your needs.See appendix B for more information about editing the/var/qmail/control/conf-common and /var/qmail/control/conf-smtpdconfiguration files.

Creating the concurrencyincoming control file is optional.  You can usethis file for setting the maximum number of concurrent connections allowed,or instead edit the appropriate section of /var/qmail/control/conf-common.If neither action is taken, qmail will limit the number of possibleconcurrent incoming SMTP connections to 40.

All log files under /var/log already exist by this point, as does the/service directory.  You will need to create the symbolic links within the/service directory.  Note that qmail will *not* start automatically afterthese links are created, *unless* svscan is running (see the notes above forLWQ section 2.7).

2.8.2.3.  This section is not necessary if you used the optional "emerge"command for extra automatic configuration, described above.  Otherwise,perform the steps in this section as given.  Note that this sectionexpects you to have created the /var/qmail/bin/qmailctl script given in LWQsection 2.8.2.1.

2.8.3.  If you haven't done so already, now is a good time to remove anyother virtual/mta packages from your system.  For example, you can run thesecommands to remove ssmtp:

emerge -C mailbaseemerge -C ssmtp

Note that you should first undo any configuration you may have performed torun another email server on your system, such as having it startautomatically during system boot.

If qmail services began running while another virtual/mta package was stillbeing utilized, stop qmail as documented in this step.  You can use theqmail-control script to do so if you decided not to create qmailctl.

The "sendmail" symbolic links will already exist by this point.

2.8.4.  The qmail ebuild creates all of the .qmail files under/var/qmail/alias mentioned in this section.  The .qmail files are empty,which means any email bound for the affected addresses will be directed touser alias's maildir.  If this is not the behavior you want, follow LWQ'sinstructions for editing these files.

2.8.5.  Again, svscan should be running before you try to start (orrestart) qmail using qmailctl (or qmail-control).  See the notes for LWQsection 2.7 above.

2.9.  Perform these steps as given to test your new installation.

Now follow the instructions given in LWQ section 3 to fully configure qmail toyour liking.  If you performed the optional configuration discussed above, anumber of control files documented in LWQ section 3.1 will already exist bythis point:

/var/qmail/control/me/var/qmail/control/defaultdomain/var/qmail/control/plusdomain/var/qmail/control/locals/var/qmail/control/rcpthosts

Each of these files will contain a single line, the fully qualified domainname of the machine.

Gentoo's installation of qmail allows for several extra control files inaddition to those documented in LWQ section 3.1  They are described below:

Control        Default       Used by          Descriptionbadmailto      (none)        qmail-smtpd      blacklisted To addressesbadrcptto      (none)        qmail-smtpd      blacklisted To addressesconf-common    as given      various          configuration common to allof qmail's network servicesconf-pop3d     as given      qmail-pop3d      configuration specific toqmail's POP3 serviceconf-qmqpd     as given      qmail-qmqpd      configuration specific toqmail's QMQP serviceconf-qmtpd     as given      qmail-qmtpd      configuration specific toqmail's QMTP serviceconf-smtpd     as given      qmail-smtpd      configuration specific toqmail's SMTP servicemorebadrcptto  (none)        qmail-smtpd      more blacklisted To addresses

Also, regular expressions can be used in badmailfrom and badmailto.

(NOTE:  Yes, badmailto and badrcptto provide essentially the samefunctionality.  That's what happens when a lot of different patches are used tomake a program as functional and configurable as possible.)

(NOTE:  QMTP, the Quick Mail Transfer Protocol, is an alternative to SMTP,designed by qmail's author.  QMTP is not compatible with SMTP, nor is it widelyused across the Internet.  If you wish to read more about QMTP, have a look atLWQ section 5.11, and also Daniel Bernstien's documentation for QMTP(http://cr.yp.to/proto/qmtp.txt).  More information about QMTP will be in afuture revision of this guide.)

(NOTE:  QMQP, the Quick Mail Queueing Protocol, was designed by qmail's authorto allow multiple servers running qmail to pool their messages into a singlequeue on a centralized server.  The outlying servers run a special configurationof qmail called "mini-qmail" and use QMQP to send their messages to the centralserver.  Bernstien has documentation for mini-qmail(http://cr.yp.to/qmail/mini.html) and QMQP (http://cr.yp.to/proto/qmqp.html).More information about these features will be in a future revision of thisguide.)

(NOTE:  The optional configuration discussed above will also create files"clientcert.pem", "rsa512.pem", and  "servercert.pem" in /var/qmail/control.These files are your self-signed SSL certificate and are necessary forencrypted SMTP; more information about them is provided in appendix B.5.  Theycan be safely ignored if you do not plan on using encrypted SMTP, or if youdid not emerge qmail with the "ssl" USE flag enabled.)

Part Three - After qmail Is Up and Running

Some tips for smooth operation and extended functionality.

* By default, Portage's "config file protection" extends to qmail'sconfiguration directory, /var/qmail/control.  This feature prevents qmail'sconfiguration from being blindly overwritten by any future upgrades orremovals.  Run "emerge -h config" for more information.

* Assuming you kept the default delivery instructions provided by Gentoo(/var/qmail/control/defaultdelivery), each user on your system will needa maildir named ".maildir" in his or her home directory.  See LWQ section4.1.3 for more information.

* Refer any users on your system to LWQ section 4 for information on how toexert control over their incoming email.

* LWQ section 5.2.1 provides information on how to install and configurethe POP3 server that comes with qmail.  If you decide to use this POP3server (qmail-pop3d), read through the steps given in LWQ section 5.2.1.2.If the standard checkpassword program meets your needs, then steps 1through 6 will already have been performed by the Gentoo qmail ebuild bythis point.  The supervise scripts set up by the ebuild for POP3service are different from those given in LWQ, and the differences aresimilar to those described above for qmail-smtpd./var/qmail/supervise/qmail-pop3d/run is designed to read configuration from/var/qmail/control/conf-common and /var/qmail/control/conf-pop3d.Modifying these configuration files is not necessary for standard POP3functionality, and not recommended for those running POP3 service for thefirst time.  Once you are familiar with how qmail's POP3 service operates,you can change these files to take advantage of features like alternativepassword checking programs, and POP-before-SMTP authentication.  Appendix Bprovides more information about how to edit the configuration files, if youdecide to do so.

When you are ready to offer POP3 service, run the following command to allowsvscan to automatically start and supervise the qmail-pop3d process:

ln -s /var/qmail/supervise/qmail-pop3d /service

(NOTE:  Gentoo used to provide a separate ebuild called qmail-pop3d thatwould install the necessary scripts for running qmail's POP3 server.  Thecurrent qmail ebuild provides the same functionality, therefore theqmail-pop3d ebuild is no longer necessary.)

If you created the /var/qmail/bin/qmailctl script discussed in LWQ section2.8.2.1, follow steps 7 through 12 to add features related to qmail-pop3d.If you decided to keep the /var/qmail/bin/qmail-control script instead, itis already capable of starting and stopping qmail-pop3d.

If svscan is currently running, POP3 service should now be available.

* Portage merges the dot-forward ebuild along with qmail.  dot-forwardallows people to create delivery instructions using Sendmail's format.Custom delivery instructions for Sendmail are usually kept in files named".forward", hence this package's name.  See LWQ appendix B.1 for moreinformation.

Conclusion - Any Questions?

Your qmail server should now be ready for action.  However, you may stillhave some questions or concerns.

If you are using Gentoo without many customizations, and you have a concernabout qmail's installation as performed by Portage, contact the maintainersof Gentoo, as they wish to be notified of any problems with their ebuilds.Their policy is to investigate the problem, and then notify the originalsoftware authors themselves if they determine the cause lies there.  VisitGentoo's bug page (http://bugs.gentoo.org) for more information.

If you have successfully installed qmail, but now you have a question aboutits performance and/or your configuration, the qmail mailing list is theplace to ask experienced qmail users for information.  However, please keepin mind these are people giving of their free time, and they are very tiredof reading the same questions over and over.  I cannot emphasize this enough:READ THE DOCUMENTATION and, if appropriate, CHECK YOUR LOGS before asking aquestion on the list.  LWQ, the qmail man pages, the web pages maintained byqmail's author at http://cr.yp.to, and especially the qmail mailing listarchives (http://www.ornl.gov/cts/archives/mailing-lists/qmail/) are allexcellent sources of information, and many list veterans consider all ofthese to be required reading.  Should you decide a question to the list isnecessary, list veteran Charles Cazabon has written "12 Steps to qmail ListBliss"(http://www.qcc.ca/~charlesc/writings/12-steps-to-qmail-list-bliss.html),detailing what every list veteran would like to see happen when somebody hasa question about qmail.

If you have a question or comment about this guide in particular, feel freeto email me at skunkworx@kingwoodcable.com.

Appendix A - The qmail Program Chain

This section briefly describes how the various qmail programs are set up, andhow they interact with one another to provide qmail's services.  Understandingthese interactions is essential if you plan on modifying your qmailinstallation to take advantage of additional features, such as those describedin appendix B.  This section does not go into much detail, and is also somewhatspecific to the way qmail is installed and configured on Gentoo systems.  For abetter and more general understanding of why and how these programs interactthe way they do, you are encouraged to read the referenced documentation.

The svscan init script (/etc/init.d/svscan) is used to start all of qmail'sservices.  First, an svscan (http://cr.yp.to/daemontools/svscan.html) processis created.  For every symbolic link created within the /service directory,svscan then creates and monitors two supervise(http://cr.yp.to/daemontools/supervise.html) processes.  The second superviseprocess creates and monitors a multilog(http://cr.yp.to/daemontools/multilog.html) process, which will feed the outputof the first supervise process into a log file.  The first supervise process'sactivity depends on the service.

For qmail-send, supervise executes and monitors the /var/qmail/rc script.  Bydefault, this script in turn executes qmail-start, which in turn creates allthe processes in charge of processing qmail's message queue.  These processesinclude qmail-send, qmail-clean, qmail-lspawn, and qmail-rspawn.  Man pages areavailable for these four programs, and for qmail-start.

For qmail-smtpd, supervise creates and monitors a softlimit(http://cr.yp.to/daemontools/softlimit.html) process, designed to limit theuse of system resources and prevent runaway processes.  softlimit in turncreates a tcpserver (http://cr.yp.to/ucspi-tcp/tcpserver.html) process,configured to listen for SMTP connections.  For every SMTP connectionreceived, tcpserver creates a qmail-smtpd process to handle that connection.A man page is available for qmail-smtpd.

For qmail-pop3d, supervise creates and monitors a softlimit process, which inturn creates a tcpserver process configured to listen for POP3 connections.For every POP3 connection received, tcpserver creates a qmail-popup process tohandle that connection.  qmail-popup displays to the connecting client a POP3greeting, then prompts for a login name and password.  qmail-popup thenexecutes a password checking program to verify the login name and password.If the login name and password are valid, the password checking program willthen create a qmail-pop3d process to further handle that connection;otherwise, the password checking program will exit, causing the connection tobe dropped.  Man pages are available for qmail-popup and qmail-pop3d.

(NOTE:  If you followed the instructions for adding svscanboot to /etc/inittab,svscanboot (http://cr.yp.to/daemontools/svscanboot.html) will be executedduring system boot, which in turn will create the svscan process.)

Appendix B.1 - qmail Network Service Configuration

This section explains the environment variables that can be defined in/var/qmail/control/conf-common, /var/qmail/control/conf-smtpd, and/var/qmail/control/conf-pop3d.  The values of these variables are in turn usedby /var/qmail/supervise/qmail-smtpd/run and/var/qmail/supervise/qmail-pop3d/run.

This section assumes an understanding of how the various programs interact toprovide qmail's services; see appendix A for an overview.

The configuration files provide default definitions for most of thesevariables.  The defaults will be enough for many qmail users' needs.Appendices B.2 through B.5 provide examples of how the configuration files canbe changed to enable certain features in qmail.  I *strongly* recommend leavingthese files alone until you are confident about what you are doing.

/var/qmail/control/conf-common provides definitions that affect all of qmail'snetwork services.  /var/qmail/control/conf-smtpd and/var/qmail/control/conf-pop3d provide definitions that will affect only SMTPand POP3 services, respectively.  Except where noted, these environmentvariables can be defined in conf-common or in a specific network service'sconfiguration file.  A definition in a specific network service's configurationfile will override any definition of that variable in conf-common, unless theprevious definition is incorporated into the new definition.

* MAXCONN

The maximum number of concurrent connections that tcpserver will allow.If unset, tcpserver will use its internal default of 40.  Normally, thisvalue is read from /var/qmail/control/concurrencyincoming.

* NOFILESGID

The GID of the system group that will run the tcpserver processes in chargeof providing qmail-related network services.

* QMAIL_CONTROLDIR

The directory for qmail's control files.  This will almost always be/var/qmail/control.  This variable is also defined in an /etc/env.dconfiguration file, so defining it again is really not necessary.

* QMAIL_POP3_CHECKPASSWORD

Specific to POP3.  This variable defines the program that will be executedto verify a POP3 login's name and password.  It is assumed that thisprogram provides the standard checkpassword interface, described athttp://cr.yp.to/checkpwd/interface.html, and further assumed that thisprogram can execute qmail-pop3d when a login name and password have beensuccessfully verified.

* QMAIL_POP3_POP3HOST

Specific to POP3.  This variable defines the name of the machine thatqmail's POP3 service will identify as its host.  By default, this is readfrom /var/qmail/control/me.

* QMAIL_POP3_POSTAUTH

Specific to POP3.  Normally, the password checking program defined byQMAIL_POP3_CHECKPASSWORD will execute qmail-pop3d when a login name andpassword have been successfully verified.  If this variable is defined, thepassword checking program will instead execute the program or string ofprograms given by this variable.  It is assumed that qmail-pop3d and itscommand-line arguments can be passed as the final command-line arguments ofthis program chain.

* QMAIL_POP3_PREAUTH

Specific to POP3.  After accepting a POP3 connection, tcpserver willnormally execute qmail-popup to provide the initial POP3 greeting andpassword prompt to the connecting client.  If this variable is defined,tcpserver will instead execute the program or string of programs given bythis variable.  It is assumed that qmail-popup and its command-linearguments can be passed as the final command-line arguments of this programchain.

* QMAIL_SMTP_POST

Specific to SMTP.  This variable provides command-line arguments to executeqmail-smtpd with.

* QMAIL_SMTP_PRE

Specific to SMTP.  After accepting an SMTP connection, tcpserver willnormally execute qmail-smtpd to provide SMTP service to the connectingclient.  If this variable is defined, tcpserver will instead execute theprogram or string of programs given by this variable.  It is assumed thatthat qmail-smtpd and its command-line arguments can be passed as the finalcommand-line arguments to this program chain.

* QMAIL_TCPSERVER_PRE

Normally, softlimit will execute tcpserver.  If this variable is defined,softlimit will instead execute the program or string of programs given bythis variable.  It is assumed that tcpserver and its command-line argumentscan be passed as the final command-line arguments to this program chain.

* QMAILDUID

The UID of the system user that will run the tcpserver processes in chargeof providing qmail-related network services.

* SOFTLIMIT_OPTS

Command-line arguments to execute softlimit with.  Seehttp://cr.yp.to/daemontools/softlimit.html for more information about theoptions available.

* TCPSERVER_HOST

The IP address tcpserver will listen for connections on.

* TCPSERVER_OPTS

Command-line arguments to execute tcpserver with, in addition to-x, -c, -u and -g.  See http://cr.yp.to/ucspi-tcp/tcpserver.html for moreinformation about the options available.

* TCPSERVER_PORT

The specific port of the IP address defined by TCPSERVER_HOST thattcpserver will listen for connections on.  This can be defined in theconfiguration file specific to each network service, however, conf-commonas installed by the qmail ebuild will set the value of this variable equalto that of the SERVICE environment variable.  SERVICE is defined by eachnetwork service's supervise script, "smtp" for SMTP, "pop3" for POP3, andso on.  For this to work, these services need to be defined with portnumbers in /etc/services.

* QMAILQUEUE

Normally, qmail pipes all messages through a program called "qmail-queue."qmail-queue's task is to place each message into qmail's message queue,where later it will be picked up by qmail-send for further processing anddelivery.  This environment variable, which by default is not set, allowsanother program to take the place of qmail-queue, providing the opportunityfor additional processing on each message before it is placed in the queue.See http://www.qmail.org/qqrbl for one example of a replacement qmail-queueprogram.  Note:  You better know what you are doing if you wish to takeadvantage of this feature.  If you do not replace qmail-queue with aprogram that provides at least the same functionality, you will break yourqmail installation!

Appendix B.2 - Authenticated SMTP

Gentoo's installation of qmail allows SMTP sessions to be authenticated withthe ESMTP AUTH command.  This permits you to restrict relaying priveleges topeople who have correct user names and passwords, instead of people who connectfrom certain IP addresses (the two methods can also be used together).  TheESMTP AUTH command was designed to support different methods of passwordverification, and this implementation provides the three most popular methods:PLAIN, LOGIN, and CRAM-MD5.  This makes qmail's authentication featurecompatible with most email clients currently available.

To enable authenticated SMTP, the QMAIL_SMTP_POST environment variable inthe conf-smtpd control file needs to be defined with three arguments.  The manpage for qmail-smtpd explains what these arguments should be: a hostname, apassword checking program, and an additional subprogram.  The hostname shouldbe the fully qualified domain name of your email server; it is used to generateCRAM-MD5 "challenges."  The password checking program must conform to thecheckpassword standard defined at http://cr.yp.to/checkpwd/interface.html, withone additional requirement:  If the password checking program is to supportCRAM-MD5, the program must be able to handle both unencrypted passwords andMD5-encrypted challenges and responses.  The subprogram is executed by thepassword checking program if password verification was successful; usually setto /bin/true, the subprogram must return "true" when exiting.

(NOTE:  checkpassword and other compatible programs are also used by qmail toauthenticate POP3 sessions, as explained earlier in this guide.  Whenauthenticating POP3 sessions, the subprogram argument is necessary because,after verifying a user's name and password, the password checking program isexpected to execute qmail-pop3d.  In the case of authenticated SMTP, thesubprogram really doesn't serve any purpose, which is why /bin/true isnormally used.)

The default conf-smtpd control file has configuration that, when uncommented,will enable authenticated SMTP, using cmd5checkpw as the passwordchecking program.  cmd5checkpw keeps a list of allowed user names andpasswords in /etc/poppasswd; see the cmd5checkpw man page for more details.If cmd5checkpw suits your needs, uncomment the four environment variabledefinitions in the "SMTP-AUTH" section of conf-smtpd.  Be sure to set up/etc/poppasswd as instructed by the cmd5checkpw man page for authentication towork properly.

Other password checking programs can be used.  For example, checkpassword uses/etc/passwd and/or /etc/shadow, enabling system users to use authenticatedSMTP.  To use checkpassword, edit conf-smtpd, uncommenting the four environmentvariable definitions mentioned in the above paragraph.  Then, change the linedefining QMAIL_SMTP_CHECKPASSWORD to look like this:

QMAIL_SMTP_CHECKPASSWORD="/bin/checkpassword"

Remember to restart qmail afterward.

One advantage of using checkpassword over cmd5checkpw is that passwords do nothave to be stored in an unencrypted format on the server.  This iscounterbalanced by the disadvantage of checkpassword not supporting CRAM-MD5;consequently, LOGIN or PLAIN must be used, which means passwords have to besent unencrypted across the network.

(NOTE:  You may need to change the permissions of checkpassword for it to workproperly in this case.  The program must be setuid root, otherwiseauthentication will fail.  Run "chmod 6755 /bin/checkpassword" to givecheckpassword the proper permissions.  Keep in mind that setting programs to besetuid root is generally a bad idea, and you may wish to look into otherpassword checking programs instead.)

(NOTE:  If you plan on providing POP3 and/or IMAP service, you may want to usethe same authentication data across all email services.  If you plan onproviding POP3 service using qmail's POP3 server, you can use the samepassword checking program for both POP3 and authenticated SMTP.  Have a lookat the conf-pop3d control file, and make sure the QMAIL_POP3_CHECKPASSWORDenvironment variable is set to your liking.)

For more information about authenticated SMTP and how it works, Erwin Hoffmanhas written a tutorial, available at http://www.fehcom.de/qmail/smtpauth.html.

Appendix B.3 - Outbound Authenticated SMTP

qmail can also be instructed to use authenticated SMTP when relaying email toother servers.  This is useful when you plan on routing all your email throughanother email server, such as the one provided by your Internet serviceprovider, and that server requires authentication.

If you have qmail configured to deliver all email to another server, then youshould have a single line in the smtproutes control file that looks similar tothis:

:mail.your-isp.com

To enable outbound authenticated SMTP, modify that line to include a usernameand password, both of which should be encoded in base64:

:mail.your-isp.com  

This feature was patched into qmail.  The patch's original author, JaySoffian, has documentation athttp://www.soffian.org/downloads/qmail/qmail-remote-auth-patch-doc.txt, whichincludes some Perl commands to help with base64 encodings.  There are alsoweb-based base64 encoders available.

For the security-conscious, keep in mind that base64 encoding is not the sameas encrypting, and anybody who can see your smtproutes control file can learnyour passwords.  Also, this feature uses LOGIN for authentication, which meansthe remote server must support LOGIN, and which also means your passwords willbe sent unencrypted across the network.

Appendix B.4 - POP-before-SMTP

An alternative to authenticated SMTP is POP-before-SMTP.  When aPOP-before-SMTP system is in place, any user that first checks his or herincoming email with POP3 is then permitted, for a period of time, to relayoutgoing email through the server.  POP-before-SMTP implementations accomplishthis by remembering POP3 clients' IP addresses, and looking for each SMTPclient's IP address in that list, granting relay permission if the address islisted.  The list is periodically cleaned of old IP addresses, ensuring relaypermission is not granted for longer than necessary.  While not as secure asauthenticated SMTP, POP-before-SMTP is a good solution that supports all emailclients, including those that cannot use authenticated SMTP.

POP-before-SMTP requires additional software, specifically, a program that willactually maintain the list of IP addresses permitted to relay.  Portage offersrelay-ctrl, written by Bruce Guenter, for this purpose.  Emerge this packagewith the following commands:

# emerge -p relay-ctrl

These are the packages that I would merge...

# emerge relay-ctrl

After emerge finishes, edit the conf-smtpd and conf-pop3d control files.  Thedefault installation already includes the necessary configuration in each ofthese files, commented out.  In conf-smtpd, uncomment the first two environmentvariable definitions in the section that begins with, "If you are interested inproviding POP or IMAP before SMTP..."  In conf-pop3d, uncomment the twoenvironment variable defitions in the section for POP3 before SMTP.  Aftersaving the changes, remember to restart qmail.  POP-before-SMTP should nowwork.

(NOTE:  This appendix assumes you are providing POP3 service, and that you areusing qmail-pop3d to do so.  With relay-ctrl, it is possible to use adifferent POP3 server and still provide POP-before-SMTP.  It is even possibleto provide "IMAP-before-SMTP" instead, using Courier IMAP.  These examples arebeyond the scope of this guide, however, there is documentation for relay-ctrlat http://untroubled.org/relay-ctrl/ and for Courier IMAP athttp://www.inter7.com/courierimap.html, as well as notes about enablingIMAP-before-SMTP in the default installation of conf-smtpd.)

Appendix B.5 - Encrypted SMTP

Ordinarily, SMTP communications are "in the clear," with no encryption.  Thismeans anybody who can eavesdrop on your network activity can monitor youremail traffic, snooping messages, sender and recipient addresses, and perhapseven SMTP authentication user names and passwords.  Consequently, an extentionto the SMTP protocol was drafted, providing email servers with the ability toencrypt SMTP sessions by using the ESMTP STARTTLS command.  Gentoo's qmailebuild allows encryption to be used on both incoming and outgoing SMTPconnections.

To enable encrypted SMTP, first make sure that you emerged qmail with the"ssl" USE flag enabled.  Next, you must have an SSL server certificate inplace.  If you ran the ebuild command for extra automatic configuration,described in Part Two above, then a self-signed certificate is already inplace.  If you did not run the ebuild command, you can generate aself-signed certificate by first editing /var/qmail/control/servercert.cnf,filling in information specific to your server, and then running/var/qmail/bin/mkservercert.  When the certificate generation processfinishes (using either command), three new files will appear in/var/qmail/control:  servercert.pem, the server's new self-signed certificate,used for incoming SMTP connections; clientcert.pem, which can be a separatecertificate used for outgoing SMTP connections, but which by default is thesame as servercert.pem; and rsa512.pem, the private code-key used to decryptincoming SMTP traffic.  Restart qmail after creating your certificate.

At this point, any client that supports the ESMTP STARTTLS command will beable to request an encrypted SMTP session; also, the server will automaticallyrequest an encrypted SMTP session when connecting to any remote host thatboasts ESMTP STARTTLS support.  The server is ready to go.  Furtherconfiguration is possible, providing, among other features, the ability torefuse outgoing email to remote hosts that do not support encryption, and theability to accept email from ecrypting clients that otherwise would have beenrejected.  For more information, visit the web page for Frederik Vermeulen'soriginal patch for qmail (http://inoa.net/qmail-tls/).

Note that self-signed certificates may be rejected by some servers as insecureor untrustworthy.  You may want to have a certificate signed by a mutuallytrusted Certificate Authority instead.

(NOTE:  The process of getting an SSL certificate issued by a CertificateAuthority is really beyond the scope of this guide, however, I plan to havemore information in a future revision.)

Also, be aware that encrypting your server's SMTP traffic does not guaranteethat your email is safe from prying eyes.  Email messages are sometimesrelayed through multiple servers, one or more of which may not supportencryption.  Also, email that has made it to its final destination is usuallystored unencrypted, making it possible for other users or administrators onthat server to read it.  For more complete email security, you may want toconsider using an email client that supports encrypting each email messagebefore it is sent.  Of course, this will require that the recipient be able todecrypt the message.  Further information would be beyond the scope of thisguide, but you can visit the web pages of email clients that support messageencryption, such as Mutt (http://www.mutt.org/), and the web pages ofgeneral-use encryption software, such as GnuPG (http://www.gnupg.org/).

Appendix C - Patches

Warning:  Lots of technical jargon ahead.  This section describes the patchesthat are applied to the qmail 1.03 source code by the qmail 1.03-r13 ebuild.  Ishould mention that many qmail veterans consider some of these patches to beunnecessary for general use, suggesting that one should use as pristine a copyof qmail as possible, applying only those patches that are known to be needed.If you are handy at writing and modifying ebuild scripts, you may want toconsider editing qmail's ebuild script to remove patches that do not apply toyou.  Of course, qmail has been found to run just fine with these patches, andthey do provide features many find useful, and fix bugs many find annoying orinconvenient.  Buyer beware, however:  The author of qmail makes no guaranteesabout its security beyond his original code.  Buyer beware again:  Removingpatches may result in unexpected behavior if the configuration files and scriptsare not modified appropriately.

* qregex-starttls-2way-auth (http://www.arda.homeunix.net/store/qmail/)

This patch combines several patches into one, providing several extentionsto qmail's functionality.

This patch provides the extra configuration file/var/qmail/control/badmailto, and enables the use of regular expressions tobe used in /var/qmail/control/badmailto and /var/qmail/control/badmailfrom.For more information, visit the original patch's web page(http://www.unixpimps.org/software/qregex/).

This patch also provides the ESMTP AUTH command, enabling qmail to requireauthorization before accepting messages for processing.  For moreinformation, visit the original patch's web page(http://members.elysium.pl/brush/qmail-smtpd-auth/).  See appendix B.2 fordetails on how to make use of this feature.

This patch also gives qmail the ability to use the ESMTP AUTH command whenconnecting to other SMTP servers.  See appendix B.3 for more details onoutbound authenticated SMTP.

Finally, this patch enables TLS/SSL support for encrypted SMTP sessions.See appendix B.5 for details on how to make use of this feature.

Patch written by Andrew St. Jean, based on the work of "unixpimps.org,"Krzysztof Dabrowski, "Mrs. Brisby," Frederik Vermeulen, and Neal Groothuis.

* smtp-auth-close3

According to the qmail 1.03-r13 ebuild, this patch "fixes a problem whenutilizing morercpthosts" together with ESMTP AUTH.

* qmailqueue (http://www.qmail.org/qmailqueue-patch)

This patch provides qmail with the ability to replace qmail-queue withother programs.  See appendix B.1 for more details.  Patch written by BruceGuenter.

* big-todo (http://qmail.null.dk/big-todo.103.patch)

qmail was designed to be able to handle large numbers of email messageswithout a significant slow-down.  One way it accomplishes this is bysplitting its queue into several different directories.  Many of thesedirectories are in turn split into subdirectories, ensuring that no singlefolder becomes unnecessarily large.

When a message is first accepted by qmail for processing, it is placed inthe "todo" directory.  Normally, this directory is not split intosubdirectories like certain queue directories are.  This means that if alarge number of messages enters the system before qmail has a chance toprocess them all, the todo directory could become quite large, introducing alag into the system.  This patch enables the todo directory to be split intosubdirectories, helping to prevent a sudden influx of email from being aproblem.  Patch written by Russel Nelson, with some modification by BruceGuenter.

* qmail-1.03-qmtpc (http://www.qmail.org/qmail-1.03-qmtpc.patch)

This patch allows qmail to send email to other servers using QMTP insteadof SMTP.  More information about QMTP will be in a future revision of thisguide.  Patch written by Russel Nelson.

* qmail-103 (http://www.ckdhr.com/ckd/qmail-103.patch)

Unpatched qmail will have trouble sending email to domains whose DNSservers send oversized answers to DNS queries.  This patch resolves thisissue.  Patch written by Christopher K. Davis.

* qmail-local-tabs

Unpatched qmail, when handling .qmail files whose first lines are nothing buttabs, has the potential to access an array out of range, an error morecommonly known as a memory or buffer overflow.  This bug is generallyconsidered to be minor, because qmail by this point is running as the ownerof the .qmail file and will never run as root, and also because qmail'sdocumentation states that a .qmail file should not start with an empty line.Nonetheless, this is a bug, and this patch fixes it.

* qmail-link-sync (http://www.jedi.claranet.fr/qmail-link-sync.patch)

qmail assumes that certain file commands are synchronous, that is, thecommands will not report a successful finish until the file has actuallybeen written to disk (as opposed to residing in a cache to be writtenlater).  While this assumption is true for some Unix-compatible operatingsystems and the file systems they use, it is not true for many flavors oflinux and its file systems.  The consequence is that a disruption of service,such as a power outage, could result in email being lost.  This patchworks around this issue by forcing file synchronization to take place afterthese commands.  Patch written by Frank Denis.

* big-concurrency

Unpatched qmail has an inherent maximum concurrency limit of 255.  In otherwords, the highest number of concurrent local deliveries and concurrentremote deliveries that can take place is 255 each.  This patch allows thoselimits to be as high as 65,000, though the qmail 1.03-r13 ebuild sets a newmaximum limit of 500 for each.  Patch written by Johannes Erdfelt.

* qmail-0.0.0.0

0.0.0.0 is considered to be a self-referencing IP address, similar to127.0.0.1 (though the semantics of each are not quite the same).Unpatched qmail does not treat 0.0.0.0 as a local IP address; this patchresolves that issue.  Patch written by Scott Gifford.

* errno

This patch fixes the code compatibility issue that prevents qmail 1.03 fromcompiling or running properly against versions of glibc 2.3.2 and newer.

* sendmail-flagf (http://david.acz.org/software/sendmail-flagf.patch)

qmail's sendmail wrapper does not support the "-f" option that the realsendmail does.  This patch provides that feature.  Patch written by DavidPhillips.

* qmail-maildir++ (http://www.shupp.org/patches/qmail-maildir++.patch)

Sam Varshavshik, the author of Courier and Courier IMAP, authored anextention to the maildir format called maildir++.  Among other things,maildir++ provides for multiple email subdirectories, and quota support.This patch enables qmail to make use of maildir++, allowing greatercompatibility between qmail and packages supporting maildir++, such asCourier IMAP and vpopmail.  Patch written by Bill Shupp.

* maildir-quota-fix

This patch fixes a typo in the above patch.

* qmail-date-localtime(ftp://ftp.nlc.net.au/pub/unix/mail/qmail/qmail-date-localtime.patch)

Whenever qmail needs to generate a timestamp, such as when adding a "Date:"header to an email message, it uses Greenwich Mean Time (GMT) timestamps.Most email clients know how to convert GMT into the local time zone, butsome do not.  This patch enables qmail to generate timestamps in the localtimezone instead.

* qmail-limit-bounce-size(http://www.qmail.org/www.jedi.claranet.fr/qmail-bounce.patch)

Normally, qmail will include a copy of the entire original message forthe original sender when generating a bounce message.  This patch allowsfor a new control file, "bouncemaxbytes", that states the maximum size abounce message can be.  Any bounce message that would go over this limitwill be truncated.

* qmail-smtpd-esmtp-size-gentoo

This patch provides support for the ESMTP SIZE command, allowing qmail toreject messages deemed too large before they are sent, instead of after.

* qmail-smtpd-relay-reject.gentoo

Some email servers allow their users to relay messages to non-localaddresses by creating a new email address that appears to be local.  Toillustrate, an email server local to example.com could be instructed todeliver a message to user@anotherexample.com by sending it a messageaddressed to user%anotherexample.com@example.com.  qmail by default doesNOT support this trick, as it can be easily abused by spammers who areaware of it.  However, according to some programs that test the integrity ofemail servers, qmail APPEARS to support this trick, because it does notreject up front any email messages addressed to local domains; instead, itlater bounces any messages that are not destined for valid addresses, such asthose with "%" or other extraneous characters.  Because these broken testingprograms do not check to see if their messages were actually delivered, manyqmail servers have unfortunately been incorrectly blacklisted.  This patchworks around this issue by enabling qmail to reject up front any recipientaddresses that use "%" and other such characters.

* qmail-gentoo-1.03-r12-badrcptto-morebadrcptto-accdias.diff

This patch provides for two new control files, "badrcptto" and"morebadrcptto".  They work similarly to badmailfrom, rejecting up frontany messages bound for addresses that appear in either of these files.Patch originally written by Ward Vandewege, later modified.

* qmail-popupnofd2close (http://www.dataloss.nl/software/patches/)

This patch allows checkpassword and similar programs to log error messagesto stderr.  Patch written by peter(at)dataloss.nl.

* qmail-1.03-reread-concurrency.2 (http://js.hu/package/qmail/)

This patch enables qmail to reread control files concurrencylocal andconcurrencyremote when the qmail-send process receives a HUP signal.Normally qmail has to be restarted for these files to be reread.  Patchwritten by Julian Severn-nek.

* 08-capa.diff (http://www.mcmilk.de/qmail/dl/djb-qmail/patches/)

This patch provides the POP3 CAPA command, allowing POP3 clients to get alist of all POP3 commands provided by qmail-pop3d.  Patch written by TinoReichardt.

Appendix D - Additional Software

This is a collection of additional software packages, many of which areavailable through Portage, that are useful for managing qmail and extendingits functionality.

* Courier IMAP (http://www.inter7.com/vpopmail) (ebuild available)

An IMAP server that supports the maildir format, and therefore integratesvery well with qmail.

* qlogtools (http://untroubled.org/qlogtools) (ebuild available)

A set of programs designed to analyze qmail's logs for monitoring andstatistics gathering.

* qmail-scanner (http://qmail-scanner.sourceforge.net/) (ebuild available)

A multi-purpose email scanner specifically designed to work with qmail,useful for combatting viruses, spam, and even unwanted file attachments.qmail-scanner can be configured with its own set of rules, and can also workwith other popular email tools such as SpamAssassin(http://spamassassin.org, ebuild available), F-Prot (http://www.f-prot.com,ebuild available), and many commercial virus scanners available for linux.

* qmailanalog (http://cr.yp.to/qmailanalog.html) (ebuild available)

Another set of tools for analyzing qmail's logs, written by the author ofqmail.

* vpopmail (http://www.inter7.com/vpopmail) (ebuild available)

A collection of programs designed to make the creation and management ofvirtual users and multiple email domains relatively fast and painless.

Acknowledgements

Thanks to Dave Sill for excellent qmail documentation in the form of "Lifewith qmail" and 'The qmail Handbook'.

Thanks to Charles Cazabon for invaluable help through the qmail mailing list.

Thanks to Daniel J. Bernstein for qmail itself.

Thanks to the authors and contributors of Gentoo for creating an excellentlinux distribution.

Guide Revision History

3/20/03 - First release.

3/21/03 - Corrected the statement about Gentoo's scripts not providing alimit on the number of simultaneous incoming SMTP connections.  There isalways a limit, even if it is not explicitly set.  Thanks to Dave Sill forpointing out this typo.

4/17/03 - Added a note about the incompatibility between qmail 1.03 and glibc2.3.2, and also fixed some grammatical and formatting mistakes.  glibc 2.3.1must be used to compile qmail and related packages.

5/13/03 - Added comments about the qmail ebuild's option for extra automaticconfiguration, and cleaned up some wording here and there.

5/15/03 - Added comments about the qmail-sumo and qmail-pop3d ebuilds.  Thanksto Tridib Biswas for pointing these out to me.

7/20/03 - Updated the guide to reflect recent releases of qmail and relatedebuilds for Gentoo.

11/30/03 - Rewrote several sections in part one to more accurately explainPortage's system of virtual packages and package blocking; added appendices,which will be further fleshed out in the next update; cleaned up some wordinghere and there.  This update is incomplete, pending a new version of the guideto be based on qmail ebuild 1.03-r13.

12/29/03 - Updated the guide to reflect qmail ebuild 1.03-r13.  Reorganizedthe appendices.  This update is also incomplete, as many sections in theappendices still need to be written.

12/30/03 - Corrected a statement concerning the Gentoo ebuild's initialconfiguration of qmail.  By default, qmail will accept SMTP connections fromanywhere, not just from local IP addresses.

2/8/04 - Removed information about the qmail-sumo ebuild, which is no longerin Portage.  Updated information about "Life with qmail," which is now basedon netqmail 1.05.  Updated information about glibc; the latest stable ebuildis now 2.3.2-r9.  Added a note about making sure the correct system users andgroups are in place before emerging qmail.  Added information about theqmail-control script installed by the qmail ebuild.  Reorganized the appendicesagain, and wrote sections concerning authenticated SMTP, outbound authenticatedSMTP, POP-before-SMTP, and additional qmail-related software.  The section onencrypted SMTP still needs to be written.  Cleaned up wording and formattingin various places.

2/20/04 - Wrote the section on encrypted SMTP.  Cleaned up wording in variousplaces.

2/22/04 - Fixed a typo in the section for encrypted SMTP.  "servercert.pem"was mentioned where "servercert.cnf" should have been named.

6/5/05 - Added the note that I am no longer actively maintaining this guide.