This documents the method I use to install qmail on my mail server, manage virtual users (a separate system user per domain), and any scripts I use to automate the process or au­then­ti­cate the users.

As­sump­tions

• In­stal­la­tion is on a Debian-based operating system.

• Ability to request and/or generate SSL cer­tifi­cates, and configure software (sslsvd) to use them.

• Basic knowledge of runit and log services.

• The working directory is ~/qmw.

• $domain is replaced by the virtual domain.

• $duser is replaced by the system account in control of $domain.

  • To generate the $duser from $domain, simply translate any dot (.) in $domain to a dash (-).

Purpose

• I was un­sat­is­fied with any of the cookie-cutter approaches to setting up qmail.

• I wanted to learn more about how the pieces of qmail and associated programs work together.

• I did not want email-only users to have system accounts.

Procedure

• Install runit, runit-services, and ucspi-tcp.

  • If you are not familiar with runit, then check the following sources for in­for­ma­tion. They contain some very good examples. The DJB Way, in particular, is worth reading (although it covers dae­mon­tools instead of runit).

    • The DJB Way - services, services!
    • runit - collection of run scripts

  • (optional) If you want runsvdir to log using svlogd instead of using read­proc­ti­tle, then install a re­place­ment runsvdir-start script. Understand - if you don't install this, then you will have no log files for runsvdir: You will have to check its status status using ps.

    # dpkg-divert --add /usr/sbin/runsvdir-start
    # mv /usr/sbin/runsvdir-start /usr/sbin/runsvdir-start.distrib
    # cp files/runsvdir-start.replacement /usr/sbin/runsvdir-start
    

    At this point you can either reboot or kill the runsvdir process. Either one should start the new process and start logging the results using svlogd.

    Check to make sure this worked by looking in the /var/log/runsvdir-service/current file (you must be in the adm group to read the log). NOTE: possibly revise based on the "How to kill runsv, no matter what?" mailing list thread.

• Install the necessary users and groups: Life With Qmail shows you how to set all required UID/GIDs. If you run Debian, and don't want to muck about with UID/GID creation, you can use Gerrit Pape's qmail-uid-gid package.

• Use equivs to create a dummy MTA debian package, then install that package and remove the old MTA (usually Exim). For reference, here is the ctl file I used to make the dummy MTA package.

• I will use John M. Simpson's (JMS1) combined qmail-patch. It provides me everything I need, and does not force me to keep track of the versions of multiple patches (at least, not more than two).

  Follow Life with qmail (replacing tcpserver with tcpsvd, and dae­mon­tools with runit) using the following patches.

  • Latest combined patch
  • Link-sync patch

  Do not allow qmail-smtpd to run until you've finished setting up the virtual domains and their con­trol­ling users (the next step).

• Configure qmail using for virtual domains only as a guideline.

  • Create the necessary base directory and group.

    # mkdir -p /home/mail
    # groupadd mailboxen
    

  • Multiple scripts are needed. A de­scrip­tion of each follows.

    • check­pass­word-assign.pl: Provides check­pass­word interface using users/assign as the user database.

    • gen-domain-assigns.sh: Generates assign files from the users in all virtual domains.

    • gen-global-assign.sh: Generates an assign file combining all virtual domains and any system users.

    • gen-req-aliases.sh: Generate required aliases in a given virtual domain. If your list of "required" aliases differs from mine, edit this script.

    • gen-user-mailbox.sh: Generate a mailbox and password for a user based on an email address given on the command line.

    • gen-validr­cpt­to.pl: Generate list of all email addresses valid on this system. List those email addresses one per line.

    • gen-validr­cpt­to.cdb.sh: Generate a constant database to be used as a database of all valid email addresses on this system. Requires the use of the cdbmake command and the cdbmake-12 script. Both are in the cdb package, which is listed on the cdb in­stal­la­tion web page.

  • All domain users are named for the domain they control. In example, user "weller-fahy-com" would control the domain "weller-fahy.com". When executing the commands below replace $domain with the desired domain name, and $email with the email address to forward any email for the abuse, hostmaster, mailer-daemon, postmaster, and webmaster addresses at $domain. To create a domain user to control "weller-fahy.com" do the following.

    # echo weller-fahy.com > /var/qmail/control/rcpthosts
    # echo weller-fahy.com:weller-fahy.com > /var/qmail/control/virtualdomains
    # useradd -c "weller-fahy.com mailbox user" -d /home/mail/weller-fahy.com \
        -g mailboxen -s /bin/false -m weller-fahy.com
    # gen-req-aliases.sh weller-fahy.com $email
    # gen-validrcptto-cdb.sh
    

  • For each domain name, a user is created by replacing all periods in the domain name with "-". The domain name "caterva.org" would become the user "caterva-org". To create a user to control a domain execute the following commands replacing $domain with the domain, $duser with the user to control the domain, and $email with the email of the user that will receive messages received for $domain's system aliases.

    # echo $domain > /var/qmail/control/rcpthosts
    # echo $domain:$duser > /var/qmail/control/virtualdomains
    # useradd -c "$domain mailbox user" -d /home/mail/$duser \
        -g mailboxen -s /bin/false -m $duser
    # echo $domain > ~$duser/.domain
    # gen-req-aliases.sh $duser $email
    

  • To make sure emails to the system aliases (abuse, hostmaster, mailer-daemon, postmaster, and root) on the host listed in /var/qmail/control/me are not bounced, make sure to add the following lines to /var/qmail/users/system, and ensure the proper .qmail-(system-alias) files are created with delivery in­struc­tions.

    =abuse:user:UID:GID:/home/user:::
    =hostmaster:user:UID:GID:/home/user:::
    =mailer-daemon:user:UID:GID:/home/user:::
    =postmaster:user:UID:GID:/home/user:::
    =root:user:UID:GID:/home/user:::
    

  • If any system user wants to receive mail in their home directory, and they have an email address in a virtual domain, then for each user place the following lines in the /var/qmail/users/system file.

    =duser-user:user:UID:GID:/home/user:::
    +duser-user-:user:UID:GID:/home/user:-::
    

    Assuming you want john@example.com delivered to the system user john, the following two lines would be inserted into /var/qmail/users/system.

    =example-com-john:john:UID:GID:/home/john:::
    +example-com-john-:john:UID:GID:/home/john:-::
    

    The system user john will then have complete control over both john@example.com and john-<anything>@example.com.

  • To create aliases within a domain (johnny for john, etc) link the alias to the user's mailbox. For example, if john@ex­am­ple.com should get any email addressed to john­ny@ex­am­ple.com, then execute the following commands.

    # $ cd /home/mail/example-com
    # sudo -u example-com ln -s john johnny
    # gen-validrcptto-cdb.sh
    

• For TLS/SSL encrypted con­nec­tions either generate a cer­tifi­cate or use one from a Cer­tifi­cate Authority (I usually use a cer­tifi­cate from CACert). Instead of du­pli­cat­ing effort, I would highly recommend you go to the JMS1's page describing the service-qmail-smtpd-run script which goes with his combined qmail patch. Therein you will find excellent doc­u­men­ta­tion on setting up an SMTP service and a list of the commonly used options for certain types of au­then­ti­ca­tion servers.