From Gentoo Wiki
Jump to: navigation, search


qmail is a fast, popular Mail Transfer Agent (MTA).


As only one MTA can be installed at the same time on a system, you might be required to unmerge an installed MTA. The package manager will report a block when another MTA is still installed. You can resolve this block by manually unmerging the old mail server. For example you can remove mail-mta/ssmtp (which might have been installed as the default when a program requested a mail server to be installed) with this command:

root #emerge --ask -C ssmtp


mail-mta/netqmail has several USE flags that may be desired for certain bigger setups. As this article aims at installing and configuring a basic netqmail setup, we'll add qmail plugin support with qmail-spp and ucspi-tcp support.

root #echo "mail-mta/netqmail qmail-spp" >> /etc/portage/package.use
root #echo "sys-apps/ucspi-tcp qmail-spp" >> /etc/portage/package.use
root #emerge --ask netqmail

Bug 415929

If you have Python 3 set as default, the installation of net-mail/queue-repair will fail. Selecting a Python version 2.x (use eselect python list / eselect python set) will allow the emerge of netqmail to complete; the default Python version can then be changed back to 3. Noted on 1st March 2015; apparently this bug has been present for 3 years.


The default 16MB of memory for qmail is a little sparse, so let's update the memory to 32MB to avoid memory related errors.

root #sed -i 's/16000000/32000000/' /var/qmail/control/conf-common
root #emerge --ask --config netqmail

Setting up non-root account for mail

The design of qmail has been completely around the focus of security. To this end, e-mail is never sent to the user 'root'. So now you have to select a user on your machine to receive mail that would normally be destined for 'root'. From now on in this guide, I will refer to that user as I have it in my setup, 'myusername'.

FILE /var/qmail/alias/.qmail-rootqmail-root
FILE /var/qmail/alias/.qmail-postmasterqmail-postmaster
FILE /var/qmail/alias/.qmail-mailer-daemonqmail-mailer-daemon

Or if you'd like this email to be sent elsewhere, simply put the full address in:

FILE /var/qmail/alias/.qmail-rootqmail-root
FILE /var/qmail/alias/.qmail-postmasterqmail-postmaster
FILE /var/qmail/alias/.qmail-mailer-daemonqmail-mailer-daemon

Fully Qualified Domain Name (FQDN)

Though not entirely related, for a MTA to function properly, it is imperative that its hostname is set up correctly. Under Gentoo /etc/conf.d/hostname and /etc/conf.d/net are the files responsible for this. In this example, the mail server is named foo on the domain example.com.

FILE /etc/conf.d/netSetup domain name
FILE /etc/conf.d/hostnameSetup hostname
Do not use mail.example.com just because it may be externally known as such. Use the actual name of the system.

Verifying that the FQDN is setup properly for the domain.

Files for a 2nd level domain

user $cd /var/qmail/control/
user $hostname --fqdn
user $cat me
user $cat defaultdomain
user $cat plusdomain
user $cat locals
user $cat rcpthosts

Files for a 3rd level domain

user $cd /var/qmail/control/
user $hostname --fqdn
user $cat me
user $cat defaultdomain
user $cat plusdomain
user $cat locals
user $cat rcpthosts

Creating Properly Signed Certificates

Move to the qmail control directory:

root #cd /var/qmail/control/

Upgrade the Cert Info to create a 2048bit key:

root #sed -i 's/1024/2048/' /var/qmail/control/servercert.cnf

Update the Cert Info with information pertinent to you. CN is your fully qualified domain name ie. foo.domain.com

FILE /var/qmail/control/servercert.cnfBe certain that you put in the correct CN

Create the pem files and key:

root #openssl req -new -nodes -out req.pem -config /var/qmail/control/servercert.cnf -keyout /var/qmail/control/servercert.pem

Get the contents of the request pem file:

root #cat /var/qmail/control/req.pem

Send req.pem to your CA(ie godaddy/Starfield, Versign, etc.) to obtain signed_req.pem and do:

root #cat myserver.domain.com.crt sf_bundle.crt >> servercert.pem
root #awk '/BEGIN PRIVATE KEY/,/END PRIVATE KEY/' servercert.pem > myserver.domain.com.key

Start qmail and add it to the default run level

Run the init scripts and setup supervisor links for qmail:

root #ln -s /var/qmail/supervise/qmail-send /service/qmail-send
root #ln -s /var/qmail/supervise/qmail-smtpd /service/qmail-smtpd

Start and add netqmail to the default run level:

root #/etc/init.d/svscan start
root #rc-update add svscan default


vpopmail will handle virtual domains, adding, deleting mail domains, accounts, storing passwords etc. vpopmail uses mysql in this setup, so if you don't have it running please install it.

First we need to tell qmail to use vpopmail when checking smtp passwords:

FILE /var/qmail/control/conf-smtpdtell qmail to use vpopmail for auth

Let's install and setup net-mail/vpopmail:

root #echo 'net-mail/vpopmail clearpasswd mysql' >> /etc/portage/package.use
root #emerge --ask vpopmail

Create the vpopmail database:

root #mysql -u root -p

mysql> create database vpopmail; mysql> grant select, insert, update, delete, create, drop on vpopmail.* to vpopmail@localhost identified by 'mypassword'; mysql> flush privileges;

mysql> quit

Edit /etc/vpopmail.conf and update the mysql password for the vpopmail user:

FILE /etc/vpopmail.confset the vpopmail user password
# Read-only DB
# Write DB


Finally we'll add net-mail/dovecot to talk to our email clients:

root #echo "net-mail/dovecot vpopmail -mysql -pam" >> /etc/portage/package.use
root #emerge --ask dovecot
root #etc-update -3

Add vpopmail uid info to the default dovecot config:

root #echo 'first_valid_uid = 89' >> /etc/dovecot/dovecot.conf
root #echo 'last_valid_uid = 89' >> /etc/dovecot/dovecot.conf

Edit dovecot ssl configs to pass our ssl certificate to email clients when the login to get mail securely:

FILE /etc/dovecot/conf.d/10-ssl.confset the location of your certs
ssl_cert = </var/qmail/control/servercert.pem
ssl_key = </var/qmail/control/myserver.domain.com.key
FILE /etc/dovecot/conf.d/10-auth.confedit the dovecot auth configs
disable_plaintext_auth = no
auth_mechanisms = plain cram-md5

#!include auth-system.conf.ext  comment this out, don't need it
!include auth-vpopmail.conf.ext
FILE /etc/dovecot/conf.d/auth-vpopmail.conf.extcomment out these two vpopmail lines
# [quota_template=<template>] - %q expands to Maildir++ quota
#  args = quota_template=quota_rule=*:backend=%q}}

Start dovecot and add to the default runlevel:

root #/etc/init.d/dovecot start
root #rc-update add dovecot default

See also