Guide updated on 29th of February 2016

Configure courier and courier-authlib

Adapt automatically generated SSL certificate

During package installation, all the needed courier packages have been installed.

Nevertheless, the generated SSL certificates probably do not match your needs. We 'll simply re-generate it.

Edit the files /etc/courier/imapd.cnf and /etc/courier/pop3d.cnf to match your settings :

[ req ]
default_bits = 4096
[ req_dn ]
O=Courier Mail Server
CN=Your FQDN server
emailAddress=Your e-mail adress

Re-generate certificates with correct information and with validity time of 10 years

rm -f /usr/lib/courier/*.pem
rm -f /etc/courier/*.pem

sed -i 's/-days 365/-days 3650/' /usr/lib/courier/mkimapdcert
sed -i 's/-days 365/-days 3650/' /usr/lib/courier/mkpop3dcert

dpkg-reconfigure courier-imap-ssl
dpkg-reconfigure courier-pop-ssl

OPTIONAL : If you want to use an official certificate (e.g. Signed by the free service

Start generating your private key and your certificate request :

cd /etc/courier
openssl req -new -nodes -config /etc/courier/imapd.cnf -keyout $SERVERNAME.key -out $SERVERNAME.csr

Submit your certificate request file /etc/courier/YOUR_SERVER_NAME.csr to your chosen authority.

When your certificate has been signed by your chosen authority, copy the signed certificate into the file /etc/courier/YOUR_SERVER_NAME.crt

cd /etc/courier
dd if=/dev/urandom of=/usr/lib/courier/imapd.rand count=1 2>/dev/null
/usr/bin/openssl gendh -rand /usr/lib/courier/imapd.rand 2048 > $SERVERNAME.dh
rm -f /usr/lib/courier/imapd.rand
chmod 600 $SERVERNAME.pem

cp imapd.pem imapd-orig.pem
cp $SERVERNAME.pem imapd.pem
systemctl restart courier-authdaemon
systemctl restart courier-imap-ssl

cp pop3d.pem pop3d-orig.pem
cp $SERVERNAME.pem pop3d.pem
systemctl restart courier-pop-ssl

OPTIONAL 2 : As we have a official certificate, we can also use it for STARTTLS.

This is not needed and could generate problem (especially if your certificate become expired)

cp /var/qmail/control/servercert.pem /var/qmail/control/servercert-orig.pem
chown vpopmail:vchkpw /var/qmail/control/servercert-orig.pem
cp /var/qmail/control/clientcert.pem /var/qmail/control/clientcert-orig.pem
chown root:qmail /var/qmail/control/clientcert-orig.pem
cat /etc/courier/$SERVERNAME.key /etc/courier/$SERVERNAME.crt > /var/qmail/control/clientcert.pem
chown root:qmail /var/qmail/control/clientcert.pem
cat /etc/courier/$SERVERNAME.key /etc/courier/$SERVERNAME.crt > /var/qmail/control/servercert.pem
chown vpopmail:vchkpw /var/qmail/control/servercert.pem

Configure courier-authlib

Courier-authlib is the authentification library used by all the courier components.

We 'll use the MySQL database used by vpopmail (which already contains the authentification info) instead of vchkpw method used in previous QMR guide (because it's no longer implemented/supported since version 0.60)

Please remember the settings used in step 4, you 'll need to use it again.

As courier-authlib and courier-authlib-mysql have been installed with Debian packages, we only have to configure it

Edit /etc/courier/authdaemonrc and change line 27 to match the following :


Edit /etc/courier/authmysqlrc and adapt variables to match the following (Put the password chosen in step 4)

MYSQL_SERVER        localhost
MYSQL_USERNAME       vpopmailuser

MYSQL_DATABASE        vpopmail

MYSQL_SELECT_CLAUSE    SELECT CONCAT(pw_name, '@', pw_domain) AS username,    \
            pw_passwd AS cryptpw,                    \
            pw_clear_passwd AS clearpw,                \
            '89' AS uid,                        \
            '89' AS gid,                        \
            pw_dir AS home,                        \
            '' AS maildir,                        \
            pw_shell AS quota,                        \
            pw_gecos AS fullname,                    \
            'disablewebmail=0,disablepop3=0,disableimap=0' AS options    \
            FROM vpopmail                        \
            WHERE                            \
            pw_name = '$(local_part)'                \
            AND                            \
            pw_domain = '$(domain)';                \

Eventually replace 89 by the alternate UID:GID chosen in Part 1

MYSQL_CHPASS_CLAUSE UPDATE vpopmail SET pw_clear_passwd='$(newpass)',pw_passwd='$(newpass_crypt)' WHERE pw_name='$(local_part)' AND pw_domain='$(domain)';

Restart the service to take those modifications into account

systemctl restart courier-authdaemon

Install simscan

Users comments
Gt - 19/03/2014 23:11

Also, you need to setup the supervise scripts for courierpasswd, otherwise you won't be able to change passwords inside Roundcube:

cd /var/qmail/supervise
mkdir -m 1755 courierpassd
cd courierpassd
echo '#!/bin/bash' > run
echo '/usr/bin/tcpserver 106 courierpassd' >> run
chmod 755 run
mkdir -m 755 log
cd log
mv service-any-log-run run
chmod 755 run
ln -s /var/qmail/supervise/courierpassd /etc/service/
Gt - 19/03/2014 22:14

You also need to add this to /etc/courier/authmysqlrc :

MYSQL_CHPASS_CLAUSE UPDATE vpopmail SET pw_clear_passwd='$(newpass)',pw_passwd='$(newpass_crypt)' WHERE pw_name='$(local_part)' AND pw_domain='$(domain)'
Michiel - 10/08/2013 20:44

PS..for all people who are thinking the --disable-clear-password option is making their passwords more secure: it does not:

it only substitutes the clear passwords with MD5 passwords and MD5 password hashes can be cracked in minutes...

If vpopmail supports something like SHA-2(56) it would be much better and even better if you use a strong salt with it (dovecot and mysql should support it too then).

Thibs - 22/03/2013 12:35

Thanks ! As soon as I 'll have time (not soon ;-( ), I will make a page with your suggestion !

Michiel - 15/03/2013 14:01

If someone wants to use Dovecot instead of Courier:

apt-get install dovecot-imapd

(I dont use pop3 anyore nowadays ;) )

Change /etc/dovecot/conf.d/10-mail.conf to:

mail_uid = 89
mail_gid = 89

mail_privileged_group = 89
mail_access_groups = 89

first_valid_uid = 89
last_valid_uid = 89

first_valid_gid = 89
last_valid_gid = 89

mail_location = maildir:/home/vpopmail/domains/%d/%n/Maildir

in /etc/dovecot/dovecot-sql.conf.ext:

driver = mysql

default_pass_scheme = MD5

connect = host= dbname=vpopmail user=vpopmailuser password=VPOPMAIL_PASSWORD

password_query = SELECT CONCAT(pw_name, '@', pw_domain) AS user, pw_passwd AS password FROM vpopmail WHERE pw_name = '%n' AND pw_domain = '%d'
user_query = SELECT pw_dir as home, 89 AS uid, 89 AS gid FROM vpopmail WHERE pw_name = '%n' AND pw_domain = '%d'

This is using vpopmail with MD5 Crypt password

Some extra security:

in /etc/dovecot/conf.d/10-ssl.conf

# SSL protocols to use
ssl_protocols = !SSLv2

# SSL ciphers to use
ssl_cipher_list = ALL:!LOW:!MEDIUM:!SSLv2:!EXP:!aNULL

and set the certificates accordingly.

Thibs - 06/08/2012 15:20

@ Denis : I 've just noticed I have the same as you (never tried to log on with an alias before)

Try to reconfigure vpopmail WITHOUT the option --enable-valias (with this option alias are stored in SQL table instead of .qmail files)


Denis - 03/08/2012 23:14

In my previous installation (qmail toaster & vpopmail 5.4.18) I was able to auth with user%domain.tld or user%domainalias.tld but not anymore.

Now I have to auth with @ and only with original domain.

Is it because of the mysql authentication ? Someone has a tip to fix this ?

Thibs - 29/07/2012 15:23

Tomas : Read upgrade-from-qmailrocks.php

Tomas - 15/07/2012 13:46

My previous qmr installation was without mysql support. As this new installation requires mysql and no way for vpopmail to work without mysql support.So, can anyone pls let how can i migrate my existing users id and password in mysql server.

thanks in advance

Fido - 24/03/2012 17:34

@David : Did you modified authmysql file or authmysqlrc file??

In my authmysql file it show nothing...

Thibs - 19/03/2012 20:53

@Tomaszg : Please follow the guide !

If you had followed it, the courier-authdaemon package should be installed since the step package-install.php

Tomaszg - 18/03/2012 22:43

Ok, really interesting.

I've removed all installed certificates on client, new are valid, have been installed and now I have 0x800ccc0f and can't download messages ;) Do I have to install courier-authdaemon?

David - 06/03/2012 17:57

@Alex : This is probably because your first attempt was configuring vpopmail without mysql support. You must delete vpopmail user/files and start again with the vpopmail installation from the scratch (tar ...), and then, when you will add the first user/domain it will create the needed tables.

Thibs - 29/01/2012 23:17

@Alex : you've probably missed something on vpopmail.php

Alex - 27/01/2012 14:52

I used modified authmysql file from David, but I could not get authentication.. In /var/log/mail.log give me:

mysql_query failed second time, givinig up: Table 'vpopmail.vpopmail'doesn't exist

What should I do?


Malice - 11/01/2012 12:29

Great info, using Kubuntu 11.10 I could not get email clients to recieve mail through imap, everything seem to be setup properly and working, I could not get authentication.

Searching around I found I needed to edit the /etc/courier/imapd and /etc/courier/pop3d

I changed this:

TCPDOPTS="-nodnslookup -noidentlookup"


TCPDOPTS="-nodnslookup -noidentlookup -user=vpopmail -group=vchkpw"
David - 13/11/2011 20:30

After taking a break from the setup:


Here is my modified authmysql file, used in conjunction with --disable-clear-passwd in vpopmail:

MYSQL_SERVER localhost
MYSQL_USERNAME vpopmailuser
MYSQL_PASSWORD mysupersecretpassword
MYSQL_SELECT_CLAUSE SELECT CONCAT(pw_name, '@', pw_domain) AS username,\
      pw_passwd AS cryptpw,\
      '' AS clearpw,\
      '89' AS uid,\
      '89' AS gid,\
      pw_dir AS home,\
      '' AS maildir,\
      pw_shell AS quota,\
      pw_gecos AS fullname,\
      'disablewebmail=0,disablepop3=0,disableimap=0' AS options\
FROM vpopmail\
pw_name = '$(local_part)'\
pw_domain = '$(domain)';

Tested and works fine with: 

/usr/sbin/authtest brol2


Authenticated:  (uid 89, gid 89)
Home Directory: /home/vpopmail/domains/
Maildir: (none)
Encrypted Password: $1$z0I8PtGe$mUp7o0UTVY7nrkZKKo0YW.
Cleartext Password: brol2
Options: disablewebmail=0,disablepop3=0,disableimap=0
Deltaflyer - 27/03/2011 00:43

I had to uncomment the MYSQL_SOCKET line in the /etc/courier/authmysqlrc file.
Otherwise I was not able to authenticate.

Color Coded Qmail Installation Key
  Regular Black Text     Qmail installation notes and summaries by the author.
  Bold Black Text     Commands to be run by you, the installer.
  Bold/Regular Red Text    Vital and/or critical information.
  Regular Blue text     Denotes helpful tips and hints or hyperlinks.
  Regular Orange Text     Command line output.
  Bold/Regular green text     Denotes the contents of a file or script.