SourceForge Logo



General setup

   In order to install this software you need to take the following simple steps:
  • 1. edit config.h to set the following parameters:
    • QMAILDIR - the root directory of your qmail installation, e.g. /var/qmail
    • QMAIL_SMTPD_NOAUTH - the new name of qmail-smtpd. See step 8
    • SSL_HACK_PASS - the ssl-hack password file (read "Providing secure pop3 with sslwrap")
    • DBHOST - the database server address
    • DBNAME - the database name
    • DBUSER - the username used for connecting to the database
    • DBPASS - the password used for connecting to the database
    • EXP_TIME - how long (in seconds) we should allow a client to send mail using us after s/he last authenticated through pop3
    • ALRM_TIME - how often (still in seconds) we should check for expired IPs. It is better to leave this to its default value of 60 seconds if you set an integer number of minutes for EXP_TIME.
    • SYSLOG_FIFO - the fifo where syslogd will send us authentication data. See below for further details.
    • CHECK_DAEMON_IPOP3D - uncomment this line if you are running wu's ipop3d at your site
    • CHECK_DAEMON_VCHKPW - uncomment this line if you are using vpopmail
    • CHECK_DAEMON_HACKED_QMAILPOP3D - uncomment this if you are using the patched version of qmail-popup and qmail-pop3d that I provide with this package
    • CONFIGURED - this check is here to make sure you read config.h. You have to uncomment this line in order for compilation to work.

    Note: you can tell pop3-authd to look for messages from all the 3 currently supported pop3 daemons at the same time.
  • 2. auth-relay needs libpq for postgres binding, so you have to have postgres or at least libpq installed on the machine. If you don't, get it at http://www.postgresql.org, it's great software. If you do (or AFTER you do) and you installed it in another place than /usr/local/pgsql, edit auth-wrap/Makefile and pop3-authd/Makefile and set the include and libs directories of the postgres installation to where they are on your system. A common case is Linux RedHat systems with a default Postgres installation. RedHat installs headers in /usr/include/pgsql and libs in /usr/lib, so change PGSQL_INCS and PGSQL_LIBS to the respective directories.
  • 3. type make. It should work. If it doesn't and you're sure it should (i.e. you've set up everything right so far), mail me with the problem and I'll try to fix it. If you can fix it yourself and mail me the solution too I'd be even happier.
  • 4. create a database with the name you specified in config.h (default "pop3authd"). Connect to it and run the pop3authd.sql script. Example:
    	pgsql -d pop3authd -U postgres -f pop3authd.sql
  • 5. create the fifo you specified in the config.h file using mkfifo. Example:
    	mkfifo -m 600 /var/pop3-auth/fifo
    Here I assume that the directory /var/pop3-auth already exists, mkfifo doesn't automatically create directories.
  • 6. instruct syslogd to send pop3 authentication messages to the fifo you've just created. For this you need to know the facility and priority with which your pop3 daemon logs the authentication messages. The facility defaults to mail, so the line you should add to your /etc/syslog.conf is:
    mail.*			|/var/pop3-auth/fifo
    You can leave your old mail.* line untouched, syslogd will still deliver messages there. Also, you can pass any messages to that fifo, but make sure that among them you also pass authentication messages, otherwise it won't work.
  • 7. copy the executable pop3-authd somewhere. Run it, it should say "starting" in the logs and go in the background. If it doesn't crash, make it run at startup. If it dies, make sure it can read the fifo (the command given as an example above creates the fifo mode 600, so it can only read it if it runs as root). If it can read it and it still dies, send a bug report including any messages it wrote in the logs. If it core dumps it would also help if you could compile it in debug mode (edit its Makefile, comment the CFLAGS and LDFLAGS which are marked "production" and uncomment those marked "debug", do "make clean" and then "make"), run it and attach the resulted core to the bug report.
  • 8. rename your current qmail-smtpd file into qmail-smtpd.noauth or whatever you specified in config.h for QMAIL_SMTPD_NOAUTH. Copy the executable auth-wrap in the bin/ directory of your qmail root and rename it qmail-smtpd.
  • 8b. alternatively, you could simply copy the original qmail-smtpd to qmail-smtpd.noauth and leave it untouched. Then make a tcpserver bind to an arbitrary port and run auth-wrap:
    	tcpserver -x /etc/tcp.smtp.cdb -v -u 0 -g 0 0 10101 \
    		/var/qmail/bin/auth-wrap 2>&1 | /var/qmail/bin/splogger smtpd 3 &
    (or whatever suits your system). This way you can test delivery using port 10101 (in this example) while still having a working mail delivery system. When you're sure it works, just rename auth-wrap into qmail-smtpd and kill the tpcserver started above.
  • 9. you're done, test things. Again, if something goes wrong, send a bug report and I'll try to fix it.

The problem with qmail's pop3 daemons

QMail's pop3 daemons require an external program for authenticating users. They do not do any authentication at all, and that's why they don't write anything in the system logs. pop3-authd relies on authentication data coming from syslog to catch IPs which should be relayed. Some external programs write data to syslog, and some don't. Anyway, the outputs of 2 different authentication programs are different, so it's hard to make pop3-authd understand all formats.
Instead, I provide patched versions of qmail-pop3d and qmail-popup along with auth-relay. These modified daemons solve the problem independently of the authentication program used. To install them you need to:
  • 1. get a source distribution of qmail and unpack it
  • 2. copy the 3 files from qmail-pop-hack/ into the qmail source tree
  • 3. build qmail again and replace the old daemons with the new ones
  • 4. make sure you compiled pop3-authd with CHECK_DAEMON_HACKED_QMAILPOP3D enabled in config.h
However, pop3-authd understands data output by vpopmail's vchkpw. Be careful not to compile support for vchkpw if you plan on using my hacked qmail-pop* daemons, especially if you want to provide pop3-ssl with sslwrap (see below).

Providing secure pop3 with sslwrap

SSLwrap by Rick Kaseguma is often used to tunnel pop3 connections through ssl. It binds to port 995 and forwards requests to port 110, making sure to encrypt outgoing packets and decrypt incoming ones. The problem with this is that authentication queries appear to come from In order to fix the problem I have hacked sslwrap to make it send an extra "SSL host:pass" command, which will be understood by one of the hacked pop3 daemons I also provide in this package (see below). WARNING: the hacked version of sslwrap will not work with normal pop3 daemons.
To install:
  • 1. create the file you specified in config.h for SSL_HACK_PASS (default /etc/sslhack.pass) and put a password in it. This password is used by the hacked versions of sslwrap and pop3 daemon when they exchange source IP information. If this password is compromised the only thing that can happen is that a user can change the IP address which is logged as the host from which he is connecting. Don't use the provided sslhack.pass without at least looking in it, it contains the password "password".
  • 2. if you are on *BSD or any system that doesn't have a separate libdl for dlopen() and friends, edit sslwrap/Makefile and comment the EXTLIBS line underneath "For Linux".
  • 3. type "make sslwrap-hack"
  • 4. replace your old sslwrap with the new executable from sslwrap-hack.

The ipop3d hack

If you are using the combination sslwrap+ipop3d you have to install a hacked version of ipop3d if you want to relay clients authenticating through pop3-ssl, because of the reasons described in the previous section. The ipop3d-hack/ directory of the auth-relay distribution contains the needed hack for WU's ipop3d (it is based on the package imap-2000c). To install:
  • 1. get the source distribution of the wu-imap package, at least version 2000c
  • 2. copy the file ipop3d.c from auth-relay's ipop3d-hack/ directory into /where/you/unpacked/imap/src/ipopd/.
  • 3. do "make slx" or whatever make command you normally use to build imap on your system. "make slx" stands for "build for Linux-Glibc". Look into imap's Makefile to find out all the options. Note: PLEASE DO NOT EMAIL BUG REPORTS REGARDING IMAP COMPILATION PROBLEMS. if you're using a recent enough package and it doesn't compile, it's not because of my patch so please direct your support requests to the wu-imap team.
  • 4. copy the new ipop3d executable from /where/you/unpacked/imap/ipopd/ipop3d over your old one. It's not advisable to do a "make install" on the whole package, you only need ipop3d replaced and a full install might break the previous install. Copying is enough.

Issues with Vmailmgr

Vmailmgr's authentication program - checkvpw - does not log anything about authentication attempts. Besides the fact that this is annoying, it also makes it incompatible with pop3-authd, which relies on authentication data coming from syslog. To fix this you'll have to use the hacked versions of qmail-pop3d and qmail-popup that I provide. Afterwards it will work with sslwrap too. See above on how to install the hacked daemons.

Issues with Vpopmail

Vpopmail's authentication program - vchkpw - also suffers from the same unavoidable problem ipop3d does when used with sslwrap. I haven't provided a hacked version because it would be difficult to hack every authentication program out there and include support into pop3-authd for all of them. Instead, simply used the hacked qmail-pop* daemons that I included in auth-wrap. This fixes the problem independently of the authentication program. However, please note that pop3-authd does support vchkpw, but only when not using pop3-ssl. If you plan to use it with pop3-ssl also comment CHECK_DAEMON_VCHKPW in config.h and rebuild pop3-authd if necessary.


  I know that you think this is the part where I tell you that if my software suddenly turns your computer into a green-ulgy-and-mean alien spawning machine you should blame it on the stars, tarot cards, common bad luck, curses, spells, atmospheric pressure variations, solar explosions, ozone layer gaps, black cats, the government, "them", or anything else besides me. However, it is not.
  This is the part where I explain why I give so many obvious details like "mkfifo does not create directories". If you haven't noticed I was going into too much detail it's OK, you've just proven my point to the others who did. If you did, my point has just been proven to you by those I was referring at in the previous sentence.
  All this is a sequel of 15 months of working as an admin at an ISP, where I had to do tech support too. Just in case you had to know.